This repository has been archived by the owner on Sep 16, 2021. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 28
/
Copy pathAPI.txt
1065 lines (879 loc) · 54.6 KB
/
API.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
API
---
Dleyna-server-service is a middleware component. It is designed to be
launched by d-Bus activation when needed. It automatically shuts down
when the last of its clients quits or releases its connection.
Dleyna-server-service currently connects to the d-Bus session bus,
although this may change in the future. It exposes four different
types of objects:
1. A manager object. There is only ever a single instance of this
object. It can be used to retrieve a list of the DMSs on the local
area network. It is also used to perform certain server independent
tasks.
2. Server objects. One separate object is exposed for each DMS
available on the LAN. These objects expose interfaces that allow
clients to retrieve information about the servers and to browse and
search their contents.
3. Container objects. Container objects represent separate folders
within the DMS. They allow clients to browse and search the contents
of the folder to which they correspond.
4. Item objects. Represent individual pieces of media content
published by a DMS. These objects can be used to retrieve information
about media objects, such as their name, their authors, and most
importantly, their URLs.
The remainder of this document will describe the four d-Bus objects
listed above and the interfaces they support.
The Manager Object:
-------------------
There is only ever a single instance of this object. The manager
object exposes two d-Bus interfaces:
1 - com.intel.dLeynaServer.Manager.
2 - org.freedesktop.DBus.Properties.
com.intel.dLeynaServer.Manager
------------------------------
Methods:
----------
The interface com.intel.dLeynaServer.Manager contains 6 methods.
Descriptions of each of these methods along with their d-Bus
signatures are given below.
GetServers() -> ao
GetServers takes no parameters and returns an array of d-Bus object
paths. Each of these paths reference a d-Bus object that represents a
single DMS.
GetVersion() -> s
Returns the version number of dleyna-server-service
Release()
Indicates to dleyna-server-service that a client is no longer interested
in its services. Internally, dleyna-server-service maintains a reference
count. This reference count is increased when a new client connects.
It is decreased when a client quits. When the reference count reaches
0, dleyna-server-service exits. A call to Release also decreases the
reference count. Clients should call this method if they intend to
keep running but they have no immediate plans to invoke any of
dleyna-server-service's methods. This allows dleyna-server-service to quit,
freeing up system resources.
SetProtocolInfo(s ProtocolInfo) -> void
Informs dleyna-server-service of the mime types and network protocols
supported by the client.
The explanation behind this function is a little complex. DMSs often
support a feature call transcoding. This allows them to publish each
media item they manage in a number of different formats. This is
useful as not all devices support the same set of media formats and
codecs. For example, a DMS might publish two separate URLS for a
video file. The first URL might point to the file in its original
format, e.g., to an ogg vorbis file. The second URL however, could
point to a MP4 encoded version of the same file. The second URL might
be preferable if viewing the file on a mobile device. In short,
SetProtocolInfo allows clients to specify the formats that they would
like to receive media content in. This function should be called by
all MediaPlayers. Doing so, will ensure that dleyna-server-service only
returns compatible URLs via the org.gnome.MediaItem2 interface. For
more information see the section on MediaServer2Spec below.
The Protocol info field is a comma separated list of protocol info
values. Each protocol info value consists of 4 fields separated by
colons. Unfortunately, the format is too complex to describe in this
document. The reader is referred to the UPnP Connection Manager
Service Template document (1) and the DLNA Guidelines (2) where it is
described extensively. However, an example protocol info value is
presented below, to give the reader an idea of what such a string
might look like.
"http-get:*:audio/mp4:DLNA.ORG_PN=AMR_WBplus,
http-get:*:image/jpeg:DLNA.ORG_PN=JPEG_MED"
The protocol info value above indicates that the client supports the
retrieval, via HTTP, and the playback of audio MP4 and JPEG files.
PreferLocalAddresses(b Prefer) -> void
Indicates whether local addresses should be prioritized or not. DMSs
tend to make their services available on multiple interfaces. If a DMP
and a DMS are running on the same device, the DMP will have the option
of communicating with the DMS over the loopback or the LAN. By
default dleyna-server-service will return loopback addresses to clients
running on the same device. This is not very helpful for DMCs who
need non-local addresses to pass to renderers running on other
devices. DMCs should therefore call this function with the value
FALSE before requesting any URLs from any servers.
Rescan() -> void
Forces a rescan for DMSs on the local area network. This is useful to
detect DMSs which have shut down without sending BYE messages or to
discover new DMSs which for some reason were not detected when either
they, or the device on which dLeyna-server runs, was started or joined
the network. New in version 0.0.2.
Properties:
---------
The com.intel.dLeynaServer.Manager interface exposes information via a number
of d-Bus properties. These properties are described below:
|------------------------------------------------------------------------------|
| Name | Type |m/o*| Description |
|------------------------------------------------------------------------------|
| NeverQuit | b | m | True if the service always stay in |
| | | | memory running. False if the service |
| | | | quit when the last client disconnects. |
|------------------------------------------------------------------------------|
| WhiteListEntries | as | m | The list of entries that compose the |
| | | | white list used to filter the networks. |
| | | | An Entry could be an interface name |
| | | | (eth0), an ip address (127.0.0.1) or |
| | | | a SSID (MyWiFi) |
|------------------------------------------------------------------------------|
| WhiteListEnabled | b | m | True if the Network Filtering is active.|
|------------------------------------------------------------------------------|
A org.freedesktop.DBus.Properties.PropertiesChanged signal is emitted when
these properties change.
These properties can be changed using the Set() method of
org.freedesktop.DBus.Properties interface.
Signals:
---------
The com.intel.dLeynaServer.Manager interface also exposes two signals.
FoundServer(o)
Is generated whenever a new DMS is detected on the local area network.
The signal contains the path of the newly discovered server.
LostServer(o)
Is generated whenever a DMS is shutdown. The signal contains the path
of the server which has just been shutdown.
The Server Objects:
------------------
Dleyna-server-service exposes a separate d-Bus object for each DMS it
detects on the LAN. These objects serve two purposes.
1. They allow the client to retrieve information about the DMS, such
as its name, the URL of its icon, its manufacturer, etc.
2. They represent the root container of the DMS allowing clients to
search and browse the DMSs contents.
Each server object exposes three separate interfaces:
com.intel.dLeynaServer.MediaDevice, org.gnome.MediaObject2 and
org.gnome.UPnP.MediaContainer2.
com.intel.dLeynaServer.MediaDevice:
---------------------------
The com.intel.dLeynaServer.MediaDevice interface exposes information about the
DMS via a number of d-Bus properties. These properties are described
below:
|------------------------------------------------------------------------------|
| Name | Type |m/o*| Description |
|------------------------------------------------------------------------------|
| DeviceType | s | m | The UPnP type of the device, e.g., |
| | | | urn:schemas-upnp-org:device:\ |
| | | | MediaServer:1 |
|------------------------------------------------------------------------------|
| UDN | s | m | The Unique Device Name of the server. |
|------------------------------------------------------------------------------|
| RootUDN | s | o | The Unique Device Name of the root |
| | | | device, if the server is a sub-device. |
|------------------------------------------------------------------------------|
| FriendlyName | s | m | The friendly name of the media server. |
-------------------------------------------------------------------------------|
| IconURL | s | o | A URL pointing to an icon that |
| | | | graphically identifies the server |
|------------------------------------------------------------------------------|
| Manufacturer | s | m | A string identifying the manufacturer |
| | | | of the server |
|------------------------------------------------------------------------------|
| ManufacturerUrl | s | o | A URL pointing to the manufacturer's |
| | | | web site. |
|------------------------------------------------------------------------------|
| ModelDescription | s | o | A description of the server. |
|------------------------------------------------------------------------------|
| ModelName | s | m | The model name of the server. |
|------------------------------------------------------------------------------|
| ModelNumber | s | o | The server's version number |
|------------------------------------------------------------------------------|
| SerialNumber | s | o | The server's serial number |
|------------------------------------------------------------------------------|
| PresentationURL | s | o | The presentation URL of the server, |
| | | | i.e., a link to it's HTML management |
| | | | interface. |
|------------------------------------------------------------------------------|
| DLNACaps | a{sv} | o | Represents the device capabilities as |
| | | | announced in the device description |
| | | | file via the dlna:X_DLNACAP element. (1)|
|------------------------------------------------------------------------------|
| SearchCaps | as | m | List of property names that can be used |
| | | | in search queries. |
| | | | A wildcard (“*”) indicates that the |
| | | | device supports search queries using |
| | | | any property name(s). |
| | | | Empty if not supported by the device. |
|------------------------------------------------------------------------------|
| SortCaps | as | m | List of property names that can be used |
| | | | to sort Search() or Browse() action |
| | | | results. |
| | | | A wildcard (“*”) indicates that the |
| | | | device supports sorting using all |
| | | | property names. |
| | | | Empty if not supported by the device. |
|------------------------------------------------------------------------------|
| SortExtCaps | as | o | List of sort modifiers that can be used |
| | | | to sort Search() or Browse() results. |
| | | | Empty if not supported by the device. |
|------------------------------------------------------------------------------|
| FeatureList | a(ssao) | o | Each element in the FeatureList array |
| | | | represents a feature supported by the |
| | | | DMS. Each feature contains three pieces |
| | | | of information, a name, a version number|
| | | | and an array of object paths that can |
| | | | clients can use to take advantage of the|
| | | | feature. There are three standardized |
| | | | feature names, BOOKMARK, EPG and TUNER. |
|------------------------------------------------------------------------------|
| ServiceResetToken | s | o | A string containing the current |
| | | | service reset token of the server. |
|------------------------------------------------------------------------------|
| SystemUpdateID | u | m | An integer value that is incremenented |
| | | | every time changes are made to the DMS. |
|------------------------------------------------------------------------------|
| Sleeping | b | o | An boolean value which represents the |
| | | | server sleeping state. |
|------------------------------------------------------------------------------|
(* where m/o indicates whether the property is optional or mandatory )
(1) A value of -1 for the srs-rt-retention-period capability denotes an
infinite retention period.
All of the above properties are static with the sole exception
of SystemUpdateID. A org.freedesktop.DBus.Properties.PropertiesChanged signal
is emitted when this property changes.
Methods:
---------
The com.intel.dLeynaServer.MediaDevice interface currently exposes 8 methods:
UploadToAnyContainer(s DisplayName, s FilePath) -> (u UploadId, o ObjectPath)
UploadToAnyContainer allows a client to upload a local file to a DMS.
The DMS chooses the best place to store the file based on the file's
type. DisplayName is the friendly name the DMS should associate with
the file and FilePath is a full path to the file. The successful
completion of this method indicates that the upload has begun, but has
not necessarily finished. There are two return values. The UploadId,
which can be used to monitor the progress of the upload and to
cancel it and ObjectPath, which contains the path of the newly created object.
CreateContainerInAnyContainer(s DisplayName, s TypeEx, as ChildTypes)
-> o ObjectPath
Creates a new container. The DMS chooses the best place to create
this new container. DisplayName is the name of the new container,
TypeEx is the extended type and ChildTypes is an array of extended types that
can be stored in the new folder, e.g., ['video','container'].
A special value of ['*'] indicates that no restriction is placed
on the types of objects that can be stored in the container.
The path of the newly created object is returned.
GetUploadStatus(u UploadId) -> (s UploadStatus, t Length, t Total)
GetUploadStatus returns the current status of an upload previously
started by a call to Upload or UploadToAnyContainer. Clients should
pass in the UploadId they received as a return value from either
of these two functions. This method returns three pieces of information.
i. UploadStatus, indicating the status of the upload. Four separate
values are possible. "IN_PROGRESS", "CANCELLED", "ERROR", "COMPLETED"
ii. Length, indicating the number of bytes that have been transferred so far.
iii. Total, indicating the total size of the upload.
Clients can call GetUploadStatus to retrieve the status of an upload up to
30 seconds after the specified upload has finished.
The only exception to this rule is if the DMS to which the file is being
uploaded shuts down or disappears from the UPnP network. If this happens
all active uploads to this DMS will be cancelled and the Device object
representing this DMS will disappear. As the Device object is no longer
available, clients cannot call GetUploadStatus to determine the status
of their uploads. Clients that initiate uploads should listen for
the LostServer signal. They should assume that any uploads to a DMS that
were in progress when this signal is received for that DMS, have been
cancelled.
GetUploadIDs() -> (au UploadIDs)
GetUploadIDs returns an array containing the IDs of all the outstanding upload
tasks. An empty array will be returned if no uploads are in progress on the
current device. As with GetUploadStatus, the IDs of upload tasks will be
returned by GetUploadIDs for 30 seconds after the uploads have finished.
CancelUpload(u UploadId) -> void
Cancels the upload identified by UploadId. This function has no effect if the
upload has already completed, i.e., its status is set to COMPLETED.
Cancel() -> void
Cancels all requests a client has outstanding on that server.
GetIcon(s RequestedMimeType, s Resolution) -> (ay Bytes, s MimeType)
Returns the device icon bytes and mime type according to
the RequestedMimeType and Resolution parameters.
Both RequestedMimeType and Resolution parameters are currently
reserved for future use and should be set as an empty string.
BrowseObjects(as ObjectPath, as Filter) -> aa{sv}
This method returns properties of all media objects specified by the first
parameter. The list of properties to return is specified by the second
parameter.
The first argument is an array of object paths.
The second argument is an array of property name. This is the list of
properties that would be returned for each object.
The format and the behaviour of this array is identical to the
filter argument passed to the Search and List functions.
The result is an array of property name+value dictionaries, one for each object
specified in the first argument.
In case of even a single 'Invalid path' in ObjectPath parameter, the function
will failed and return an error.
In case of 'Invalid ID', the function will succeed, and an 'Error' property
will be set for this object.
We guarantee that the number of elements of the result array is the same and in
the same order as the ObjectPath array.
The purposes of this method are:
1. It allows applications to easily retrieve information about unrelated
objects in one call.
2. It should be used in preference to GetAll, if an application wishes to
retrieve a subset of an object's properties. Browse is likely to be more
efficient than GetAll in such cases.
Wake() -> void
Sends a magic packet to the server to wake it up if it is in sleeping state.
Signals:
---------
The com.intel.dLeynaServer.MediaDevice interface also exposes three signals.
Changed (aa{sv} ChangedObjects)
The Changed signal is generated by servers to provide precise information
of changes that have taken place to their content. Changed is useful for
synchronisation controllers. It allows them to dynamically update their local
cache of the server's content. This signal contains an array of zero or more
dictionary elements, each of which represents a change to a specific object.
The dictionary is composed of the following keys:
|------------------------------------------------------------------------------|
| Key | Type | m/o | Description |
|------------------------------------------------------------------------------|
| ChangeType | u | m | Contains the Type of the notification: |
| | | | 1 (ADD) an object has been added |
| | | | 2 (MOD) an object has been modified |
| | | | 3 (DEL) an object has been deleted |
| | | | 4 (DONE) an update to a sub-tree has |
| | | | completed |
| | | | 5 (CONTAINER) a container has been updated |
|------------------------------------------------------------------------------|
| Path | o | m | Contains the Object Path property of the |
| | | | object that was changed. |
|------------------------------------------------------------------------------|
| UpdateID | u | m | ContainerUpdateID or SystemUpdateID when the |
| | | | object was changed. |
|------------------------------------------------------------------------------|
| SubTreeUpdate | b | o | True if the object was added as part of a |
| | | | subtree update. |
|------------------------------------------------------------------------------|
| Parent | o | o | Contains the Object Path property of the |
| | | | parent container of the changed object. |
|------------------------------------------------------------------------------|
| TypeEx | s | o | Contains the value of the TypeEx property |
| | | | (converted upnp:class property) of the |
| | | | object that was changed. |
|------------------------------------------------------------------------------|
| Type | s | o | Contains the value of the Type property |
| | | | (converted upnp:class property) of the object |
| | | | that was changed. |
|------------------------------------------------------------------------------|
ContainerUpdateIDs(a(ou) ContainerPathsIDs)
Is generated when the contents of one or more folders maintained by the
server have changed. This signal contains an array of paths/ContainerUpdateID
of the server containers that have changed.
UploadUpdate(u UploadId, s UploadStatus, Length t, Total t)
Is generated when an upload completes, fails or is cancelled. The first
parameter is the ID of the upload. The second contains one of three values,
"CANCELLED", "COMPLETED", "ERROR", indicating whether the upload was cancelled,
completed successfully or failed, respectively. The third parameter indicates
the total amount of bytes that were uploaded and the fourth, the size of the
file being uploaded.
Here is some example code in python that enumerates all the media
servers present on the network and prints their names and the paths of
the d-Bus objects that represent them, to the screen.
import dbus
bus = dbus.SessionBus()
manager = dbus.Interface(bus.get_object('com.intel.dleyna-server',
'/com/intel/dLeynaServer'),
'com.intel.dLeynaServer.Manager')
for path in manager.GetServers():
server = dbus.Interface(bus.get_object(
'com.intel.dleyna-server', path),
'org.freedesktop.DBus.Properties')
folderName = server.Get("", "DisplayName")
print '{0:<30}{1:<30}'.format(folderName , path)
Running this code on a LAN with 3 DMSs produces the following output:
My Media /com/intel/dLeynaServer/server/3
Root /com/intel/dLeynaServer/server/1
Test Streams /com/intel/dLeynaServer/server/4
org.gnome.MediaObject2
----------------------
The org.gnome.MediaObject2 interface exposes some basic properties of
the server's root directory. This interface is described
MediaServer2Spec specification (3). Dleyna-server-service enhances this
interface by adding new properties and methods and by defining
additional values for the Type property.
Additional Values for the Type Property:
----------------------------------------
The MediaServer2Spec Type property can be set to one of only seven
possible values: 'container', 'video', 'video.movie', 'audio',
'music', 'image' or 'image.photo'. This causes a number of problems
for dLeyna-server. First, there is only one value for container, so
it is not possible to indicate if the container is an album or a
playlist, for instance. Secondly, there is no way to represent an item
that is not an audio, video or image item, such as a generic item
(UPnP class of object.item) or a playlist item.
dLeyna-server solves these two different problems in two ways:
- It provides a new property called TypeEx, which provides extended
type information. TypeEx is a superset of Type, providing specific
values of object types that are not supported by Type. For example,
for an album, Type will be container but TypeEx will be set to
container.album.musicAlbum.
- It provides a new catch all value for Type, item.unclassified.
item.unclassified means that the object is an item but it is not
an audio, video, or image item, e.g.,a generic item or a playlist item.
The actual type of the item is stored in TypeEx. item.unclassified
may be specified as a value for the Type property in searches. In such
cases it is treated as the UPnP type object.item.
Adding an additional value to MediaServer2Spec's Type property breaks our
compliance with this spec a little, but it is necessary to achieve UPnP
certification.
Additional Properties:
----------------------
|---------------------------------------------------------------------------|
| Name | Type | m/o* | Description |
|---------------------------------------------------------------------------|
| DLNAManaged | a{sb} | o | A dictionary of boolean values |
| | | | indicating the values of the various |
| | | | DLNA managed attributes. There are 5 |
| | | | keys: Upload, CreateContainer, Delete, |
| | | | UploadDelete, ChangeMeta |
|---------------------------------------------------------------------------|
| Restricted | b | m | Indicates whether the object is |
| | | | modifiable. |
|---------------------------------------------------------------------------|
| Creator | s | o | Indicates an entity that owns the |
| | | | content or is primarily responsible for |
| | | | creating the content. |
|---------------------------------------------------------------------------|
| ObjectUpdateID | u | o | Represents a last-modified timestamp |
| | | | for the object relative to the |
| | | | SystemUpdateID state variable. |
|---------------------------------------------------------------------------|
| TypeEx | s | m | The extended Type of the object. |
| | | | TypeEx permits a superset of the values |
| | | | supported by the Type property. When |
| | | | the Type of an object is accurately |
| | | | described by Type, i.e., the object |
| | | | is a basic container or is an image, |
| | | | audio, or video file, TypeEx = Type. |
| | | | For objects where this is not the case, |
| | | | e.g., an album, the TypeEx value is |
| | | | formed by removing the |
| | | | "object." prefix from the UPnP |
| | | | class. For example, the TypeEx value |
| | | | for the UPnP class, |
| | | | object.container.playlistContainer is |
| | | | container.playlistContainer. |
| | | | |
| | | | New in version 0.2.0. |
|---------------------------------------------------------------------------|
Additional Methods:
------------------
Delete() -> void
Delete will simply call the UPnP DestroyObject method on the relevant
server side object. Note that calling Delete on the root object of a
server will delete all the contents on the server but not the
device object itself.
Update(a{sv} ToAddUpdate, as ToDelete) -> void
Updates the meta data of an existing DMS object. It is based on the
MediaServerAv UpdateObject command. ToAddUpdate is a dictionary of
property name value pairs that are to be updated, or added if they do
not already exist. ToDelete is an array of properties to be deleted.
The same property cannot appear in both ToAddUpdate and ToDelete.
Only the following properties can be updated: 'Date', 'DisplayName',
'Artists', 'Album', 'TypeEx', 'TrackNumber'.
GetMetaData() -> s
Returns the object meta data information in DIDL-Lite XML format. This
is useful when writing Digital Media Controllers. The controllers can
pass this information to the DMR which can use it to determine the server
side streaming options for the object. New in v0.0.2.
org.gnome.MediaContainer2
----------------------
The org.gnome.MediaContainer2 interface exposes some additional
properties of the root directory. It also provides methods that can
be used by clients to perform a recursive search on the root directory
and to retrieve a list of its children. The org.gnome.MediaContainer2
interface is documented in the MediaServer2Spec (3). However,
dleyna-server-service's implementation of org.gnome.MediaContainer2
differs slightly from the specification. These differences can be
grouped into two categories: unsupported properties and new methods.
Unsupported Properties:
-----------------------
The properties org.gnome.UPnP.MediaContainer2.ItemCount and
org.gnome.UPnP.MediaContainer2.ContainerCount are not implemented as
there is no way to efficiently implement these properties in
dleyna-server-service.
In addition, org.gnome.UPnP.MediaContainer2.Icon is not supported
either as its implementation is really complicated, requiring the
creation of virtual objects. Furthermore, it cannot be properly
implemented in dleyna-server-service as the UPnP servers do not provide
us with enough information to populate the mandatory properties for
these virtual objects. Nevertheless, clients can retrieve a URL that
points to a server's icon via the com.intel.dLeynaServer.MediaDevice property
IconURL.
Please note that none of these unsupported properties are mandatory,
so their absence does not affect dleyna-server-service's compatibility
with MediaServer2Spec.
Additional properties unsupported by org.gnome.MediaContainer2
--------------------------------------------------------------
|---------------------------------------------------------------------------|
| Name | Type | m/o* | Description |
|---------------------------------------------------------------------------|
| CreateClasses |a(sb) | o | The CreateClasses property is an |
| | | | array of tuples (sb) that lists |
| | | | the extended types of objects that|
| | | | that can be created in a |
| | | | container. A boolean value is |
| | | | associated with each type. This |
| | | | boolean indicates whether objects |
| | | | of types derived from the |
| | | | specified extended type can also |
| | | | be created in this container. |
| | | | For example, |
| | | | ("container.album.","true") |
| | | | would indicate that objects of |
| | | | type container.album, |
| | | | container.album.music and |
| | | | container.album.photo can be |
| | | | created in the container. |
|---------------------------------------------------------------------------|
| ContainerUpdateID | u | o | Contains the value of the |
| | | | SystemUpdateID state variable |
| | | | generated by the most recent |
| | | | container modification for that |
| | | | container |
|---------------------------------------------------------------------------|
| TotalDeletedChildCount | u | o | Contains the total number of |
| | | | child objects that have been |
| | | | deleted from a container object |
| | | | since the last initialization |
|---------------------------------------------------------------------------|
| Resources |aa{sv}| o | Returns the set of resources |
| | | | associated with a container. |
| | | | New in v0.0.2 |
|---------------------------------------------------------------------------|
| DLNAConversion | a{sb}| o | |
| DLNAFlags | a{sb}| o | |
| DLNAOperation | a{sb}| o | See "Container properties" |
| DLNAProfile | s | o | paragraph below. New in v0.0.2 |
| MIMEType | s | o | |
| Size | x | o | |
| UpdateCount | u | o | |
| URLs | as | o | |
|---------------------------------------------------------------------------|
Container properties:
---------------------
Each container may expose one or more resources via the Resources
property. Each resource typically represents a playlist, containing
references (often URLs) to the container's media items. Multiple
resources may be specified for a single container as the DMS may
support different playlist formats, e.g., M3U, DIDL-S, etc. The
properties of one of these resources may be duplicated directly in the
Container object itself. The algorithm for selecting this resource
is given in the section "Transcoding and org.gnome.UPnP.MediaItem2".
In MediaItem2 section also, you will find the definition for these properties
in Resources/Additional properties.
New Methods:
------------
Eight new methods have been added. These methods are:
ListChildrenEx(u Offset, u Max, as Filter, s SortBy) -> aa{sv}
ListItemsEx(u Offset, u Max, as Filter, s SortBy) -> aa{sv}
ListContainersEx(u Offset, u Max, as Filter, s SortBy) -> aa{sv}
SearchObjectsEx(s Query, u Offset, u Max, as Filter, s SortBy) -> (aa{sv}u)
Upload(s DisplayName, s FilePath) -> (u UploadId, o ObjectPath)
CreateContainer(s DisplayName, s TypeEx, as ChildTypes) -> o ObjectPath
CreateReference(o ObjectPath) -> o ObjectPath
GetCompatibleResources(s protocol_info, as filter) -> a{sv}
The first four methods are identical in function and behaviour to
existing the MediaServer2Spec functions ListChildren, ListItems,
ListContainers, and SearchObjects, with the exception that they take
one extra parameter, and in the case of SearchObjectsEx, return an
extra result.
This extra parameter allows clients to specify a sort
order for the returned items. It is a string that specifies a comma
separated list of PropertyNames, identifying the order in which
returned items should be sorted. Each property name can be preceded
with a '-' or a '+' to indicate descending or ascending order
respectively. An example, is "+Date,-DisplayName", which will sort
the return items first by date in ascending order and then by name in
descending order. White space is not permitted in this string.
The return signature of SearchObjectsEx is (aa{sv}u). Note the extra
integer return value after the dictionary of objects. This integer
contains the total number of items matching the specified search as
opposed to the total number of objects contained in the returned dictionary
of objects. These two values may differ if the client has used the
Offset and Max parameters to request a portion of the total
results returned, because for example its screen is only capable of
displaying 20 objects at any one time. Knowing the total number of
objects that match a search is useful for applications.
It allows them to inform the user as to the total number of matches
and to correctly compute the scrollbars of the list displaying
the found items.
A small Python function is given below to demonstrate how these new
methods may be used. This function accepts one parameter, a path to a
d-Bus container object, and it prints out the names of all the
children of that object in descending order.
def list_children(server_path):
bus = dbus.SessionBus()
container = dbus.Interface(bus.get_object(
'com.intel.dleyna-server', path),
'org.gnome.UPnP.MediaContainer2')
objects = container.ListChildrenEx(0, 0, ['DisplayName'], "-DisplayName")
for item in objects:
for key, value in item.iteritems():
print '{0:<30}{1:<30}'.format(key, value)
The output of this function might look something like this:
DisplayName Videos
DisplayName Pictures
DisplayName Music
DisplayName Files & Folders
when the server_path parameter contains the path of a server object.
The fifth new method, Upload, allows clients to upload a local file to
the org.gnome.UPnP.MediaContainer2 object upon which it was executed.
It is identical in function and behavior to
com.intel.dLeynaServer.MediaDevice.UploadToAnyContainer with the sole
exception that Upload allows the client to specify the server-side
container into which the file is to be uploaded whereas
UploadToAnyContainer leaves it up to the server to determine the most
suitable location for the file.
The CreateContainer method creates a new child container.
DisplayName is the name of the new container,
TypeEx is the extended type and ChildTypes is an array of extended
types that can be stored in the new folder, e.g., ['video','container'].
A special value of ['*'] indicates that no restriction is placed
on the types of objects that can be stored in the container.
The path of the newly created object is returned.
The CreateReference method creates a reference in the container to the object
identified by the ObjectPath parameter. This method returns the d-Bus path of
the newly created reference. CreateReference is useful when creating
server side playlists. CreateContainer can be used to create a new playlist,
and CreateReference can be used to add items to that playlist.
The GetCompatibleResources method: see description in MediaItem2.
Recommended Usage:
------------------
All of the list and search functions supported by dleyna-server-service's
implementation of org.gnome.UPnP.MediaContainer2 contain three
parameters that should be used to improve the efficiency and
responsiveness of applications built using dleyna-server-service.
The first two parameters of interest are offset and max. These
parameters allow the client application to retrieve the contents of a
directory, or the results of a search, in chunks. This is vital if
the client's user interface is limited to displaying a fixed number,
let's say 30, items on the screen at any one time. Suppose the client
performs a search which has 2000 results. If it passes the Search or
SearchEx method an offset and a max of 0, all of the results will be
returned to the client at once, even though it is only capable of
display 30 items at a time. This will increase the memory
requirements of the client and reduce its responsiveness as it must
wait until all 2000 items have been received before it can update the
UI. Also, if the user locates the item he is looking for in the first
page of items, a lot of network and IPC traffic will have been
generated in vain. For these reasons, it is better to retrieve items
in chunks, as needed.
The amount of network and IPC traffic can be reduced further by
prudent use of the filter parameter. This parameter is an array of
strings, each element of which corresponds to a property name. If the
client invokes a function specifying a filter parameter that is set to
a single element array containing the string '*', dleyna-server-service
will include all the properties of all the requested objects in the
result. However, often the client only needs to know a subset of
these properties. A UI that displays results of a search might only
want to display the names and perhaps the dates of the items that
match the search. Once the user has identified the item he is looking
for, the remaining properties for that item, and only that item, can
be retrieved. As an example, consider the list_children function
above. It requests that only the DisplayName of each of the
containers' children be returned. Replacing ['DisplayName'] with
['*'] will generate a lot more output.
Container Objects:
------------------
Container objects represent folders in a DMS. In order to manipulate
a container object one first needs to discover its path. This can be
done by calling one of the List or Search methods implemented by the
server object or another container object. Note that a server object
is also a container object so a container object can be constructed by
using a server's d-Bus object path.
Container objects support two interfaces: org.gnome.MediaObject2 and
org.gnome.MediaContainer2. Both of these interfaces have been
described in detail above and will not be discussed further in this
section.
An example of how container objects can be used is given in the
following function.
def tree(server_path, level=0):
bus = dbus.SessionBus()
container = dbus.Interface(bus.get_object(
'com.intel.dleyna-server', server_path),
'org.gnome.UPnP.MediaContainer2')
objects = container.ListChildren(0, 0, ["DisplayName", "Path", "Type"])
for props in objects:
print " " * (level * 4) + ( props["DisplayName"] +
" : (" + props["Path"]+ ")")
if props["Type"] == "container":
tree(props["Path"], level + 1)
When given the path of a container, and this could be a server object
which acts as a root container, it recursively prints the contents of
that container in depth first order. For example, to dump the entire
contents of the My Media server introduced above, one would simply
need to invoke tree("/com/intel/dLeynaServer/server/3").
Item Objects:
-------------
Item objects represent a unique piece of media that can be downloaded
or streamed. Each item object implements the
org.gnome.UPnP.MediaObject2 interface, which is described above, and
the org.gnome.UPnP.MediaItem2 interface that is documented in the
MediaServer2Spec (3). Although the org.gnome.UPnP.MediaItem2 is
documented elsewhere, there are some peculiarities of its
implementation in dleyna-server-service that merit further explanation.
These are described in the sections below.
Transcoding and org.gnome.UPnP.MediaItem2
-----------------------------------------
As mentioned above, DMSs often provide different representations of
the same media file. Separate sets of meta data, such as a mime type,
a URL, a size, a ColorDepth, etc., are associated with each
representation. Unfortunately, it is difficult to represent this in
org.gnome.UPnP.MediaItem2. Although, org.gnome.UPnP.MediaItem2,
allows multiple URLs to be specified, it only permits a single set of
meta data to be associated with each item. For example, the MIMEType
property is a single string and not an array. If multiple URLs were
associated with the same item, one would not know to which URL the
MIMEType property pertained. For this reason, dleyna-server-service only
ever returns one element in the URLs property. By default, the value
of this URL and all of the meta data properties that can change with a
representation (MIMEType, DLNAProfile, Size, Duration, Bitrate,
SampleRate, BitsPerSample, Width, Height, ColorDepth) refer to the
first representation returned by the DMS for this item. However, the
client can change this behaviour by calling
com.intel.dLeynaServer.Manager.SetProtocolInfo. If this is done,
these properties correspond to the first representation returned by
the server that is compatible with the specified protocol info. If no
representations are compatible, these properties will not be present
in the item.
Resources
----------
Dleyna-server-service offers a second solution to the above problem that
may be useful in certain programming environments. It implements a
non standard property called "Resources" which is an array of
dictionaries. Each dictionary represents a separate representation of
the item and contains all the properties, including the MIMEType and
the URL that pertain to that representation. This can be convenient
if you wish to display the media item in a web browser. You can
simply create a video or an audio tag with one source for each element
in the resources array and then let the browser work out which one
suits it best. The specification for the Resources property is given
in the table below:
|---------------------------------------------------------------------------|
| Name | Type | m/o* | Description |
|---------------------------------------------------------------------------|
| Resources |aa{sv}| m | Returns the set of resources associated |
| | | | with an item |
|---------------------------------------------------------------------------|
The names of the properties included in this array are identical to
the names of the org.gnome.UPnP.MediaItem2 properties to which they
correspond, e.g., MIMEType, Size.
However, four additional properties are included.
Please note that if you want the resource properties to be included in the
results of a call to one of the List or the Search functions, and you
are explicitly filtering properties, you must include "Resources" in
the filter array. The filter parameter also applies to the contents
of the returned resources. So if you specify a filter of ["MIMEType",
"URL", "Resources"] the dictionaries in the resources array will contain
only these properties.
dLeyna-server defines four additional resource properties. These have been
added to improve our DLNA support.
|---------------------------------------------------------------------------|
| Name | Type | m/o* | Description |
|---------------------------------------------------------------------------|
| DLNAConversion | a{sb} | o | Indicates whether the content of the |
| | | | Resource is in original source format |
| | | | or if the content is transcoded. |
| | | | There is 1 key: Transcoded. |
| | | | See Reference (4): DLNA.ORG_CI. |
| | | | |
| | | | New in v0.0.2 |
|---------------------------------------------------------------------------|
| DLNAFlags | a{sb} | o | A dictionary of boolean values |
| | | | indicating the values of the various |
| | | | operations supported by a resource. |
| | | | There are 12 keys: |
| | | | SenderPaced, TimeBased, ByteBased, |
| | | | PlayContainer, S0Increase, SNIncrease |
| | | | RTSPPause, StreamingTM, InteractiveTM |
| | | | BackgroundTM, ConnectionStall, DLNA_V15 |
| | | | See Reference (5): DLNA.ORG_FLAGS. |
| | | | |
| | | | New in v0.0.2 |
|---------------------------------------------------------------------------|
| DLNAOperation | a{sb} | o | A dictionary of boolean values |
| | | | indicating the values of the various |
| | | | DLNA Operation attributes. There are 2 |
| | | | keys: RangeSeek and TimeSeek. |
| | | | See Reference (6): DLNA.ORG_OP. |
| | | | |
| | | | New in v0.0.2 |
|---------------------------------------------------------------------------|
| UpdateCount | u | o | Contains the number of times the |
| | | | implementation detects that a change |
| | | | was made to the resource. |
| | | | |
| | | | New in v0.0.2 |
|---------------------------------------------------------------------------|
GetCompatibleResource
------------------------
A third option is provided to make the lives of DMC authors easier.
In a DMC, the best resource is defined not by the local device but by
the capabilities of the renderer chosen by the user to play the given
item. Once the user selects a file to play and a renderer upon which
to play it, the DMC needs to retrieve the renderer's Sink
ProtocolInfo. It can then pass this data directly to a new function
that dleyna-server-service adds to the org.gnome.UPnP.MediaItem2
interface, called GetCompatibleResource. GetCompatibleResource
returns a dictionary of properties that corresponds to the item
representation that best matches a specified protocol info. The
signature of GetCompatibleResources is given below:
GetCompatibleResources(s protocol_info, as filter) -> a{sv}
The first argument is a comma separated list of protocol info values,
as described above. The second argument is an array of properties to
be included in the returned dictionary. The format and the behaviour
of this array is identical to the filter argument passed to the Search
and List functions.
Additional Properties
---------------------
Dleyna-server-service defines some additional properties for