Sorry, you need to enable JavaScript to visit this website.

Feedback

Your feedback is important to keep improving our website and offer you a more reliable experience.

dLeyna

As an umbrella project, dLeyna hosts a cluster of middleware components for the implementation of Digital Media Servers, Digital Media Renderers, Digital Media Controllers and Digital Media Players. These readily available APIs enable consumer electronics system builders to reduce Build-of-Material costs and time-to-market.

dLeyna-server exposes a separate d-Bus object for each DMS it detects on the LAN. These objects serve two purposes:

  • They allow the client to retrieve information about the DMS, such as its name, the URL of its icon, its manufacturer, etc.
  • They represent the root container of the DMS, allowing clients to search and browse the DMS's contents.

Each server object exposes three separate interfaces:

  • com.intel.dLeynaServer.MediaDevice
  • org.gnome.MediaObject2
  • org.gnome.UPnP.MediaContainer2

com.intel.dLeynaServer.MediaDevice

The com.intel.dLeynaServer.MediaDevice interface contains properties that provide clients with information about DMSs, methods to perform various DMS specific functions and signals that inform clients when certain DMS events have taken place.

Properties

The com.intel.dLeynaServer.MediaDevice interface exposes information about the DMS through 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, such as, urn:schemas-upnp-org:device:MediaServer:1
UDN s m The Unique Device Name of the server.
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, that is, a link to its HTML management interface.
DLNACaps a{sv} o Represents the device capabilities as announced in the device description file via the dlna:X_DLNACAP element. A value of -1 for the srs-rt-retention-period capability denotes an infinite retention period.
SystemUpdateID u m An integer value that is incremented every time changes are made to the DMS.
SearchCaps as m List of property names that can be used in search queries. This property is empty if search is not supported by the device. A value of * indicates that all properties can be used in search queries.
SortCaps as m List of property names that can be used to sort Search() or Browse() action results. This property is empty if sorting is not supported by the device. A value of * indicates that all properties can be used to sort the results of queries.
SortExtCaps as m 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.

(* where m/o indicates whether the property is optional or mandatory)

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 provides the following methods:

Signature Description
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.
  1. UploadStatus, indicating the status of the upload. Four separate values are possible. "IN_PROGRESS", "CANCELLED", "ERROR", "COMPLETED".
  2. Length, indicating the number of bytes that have been transferred so far.
  3. 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.
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. 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 canceled 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 canceled.
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 outstanding requests a client has issued to the device. dLeyna-server maintains one task queue per client per DMS. Commands are placed into the relevant queue when received by dLeyna-server. All commands in a given queue are executed sequentially. This means that a given client can issue as many parallel commands to a given server as it likes, but these commands will be executed one after the other. On the other hand, commands issued to other servers or issued to the same server by different clients are processed in parallel by dLeyna-server. Calling the Cancel function for a com.intel.dLeynaServer.MediaDevice object cancels all the outstanding commands the client has issued on this object. All such commands will fail with an appropriate error.

Signals

The com.intel.dLeynaServer.MediaDevice interface also exposes two signals.

Signature Description
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 tuples (path, ContainerUpdateID), one for each modified container.
UploadUpdate(u UploadId, s UploadStatus, Length t, Total t) Is generated when an upload completes, fails or is canceled. The first parameter is the ID of the upload. The second contains one of three values, "CANCELLED", "COMPLETED", "ERROR", indicating whether the upload was canceled, 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.

org.gnome.MediaObject2

The org.gnome.MediaObject2 interface exposes some basic properties of the server's root directory. This interface is described in the MediaServer2Spec specification. dLeyna-server 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 super set 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 Identifies the entity that owns the content or is primarily responsible for creating the content.
ObjectUpdateID u o Provides an indication of when the object was last updated. It contains the value held by the SystemUpdateID when the modification was made.
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

Signature Description
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. However, dLeyna-server'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 because there is no way to efficiently implement these properties in dLeyna-server.

In addition, org.gnome.UPnP.MediaContainer2.Icon is not supported, either, because its implementation would be really complicated, requiring the creation of virtual objects. Also, it cannot be properly implemented in dLeyna-server because 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 through the com.intel.dLeynaServer.MediaDevice property IconURL.

Note: None of these unsupported properties are mandatory, so their absence does not affect dLeyna-server's compatibility with MediaServer2Spec.

New Properties

Several new properties have been added to 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 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 type can also be created in this folder. For example, ("album", true") would indicate that objects of type album, album.music and album.photo can be created in the container.
ContainerUpdateID u o Provides an indication of when the container was last updated. It contains the value held by the SystemUpdateID when the modification was made.
TotalDeletedChildCount u o Indicates the total number of child objects that have been deleted from the container object since the last initialization.
Resources aa{sv} o The set of resources associated with a container. These resources are typically playlists. Not all containers have resources. New in v0.0.2.
DLNAConversion a{sb} o 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". The meaning of the first three properties is given in the Item Objects page. The meaning of the remaining properties is given in MediaServer2Spec's description of the org.gnome.UPnP.MediaItem2 interface. Note that the first three properties probably don't make too much sense for container resources, well for playlists anyway, but are exposed for completeness. New in v0.0.2.
DLNAFlags/td> a{sb} o
DLNAOperation a{sb} o
DLNAProfile s o
MIMEType s o
Size x u
UpdateCount u o
URLs as o

New Methods

Eight new methods have been added. These methods are:

Signature
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 (New in v0.0.2)
GetCompatibleResources(s protocol_info, as filter) -> a{sv} (New in v0.0.2)

The first four methods are identical in function and behavior to the existing 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 property names, 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 of the total number of matches and to correctly compute the scrollbars of the list displaying the found items.

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.

dLeyna-server supports the retrieval of resources for containers. Sometimes a container will have one or more resources, typically when a container provides playlist files, e.g., M3U or DIDL-S for its contents. These playlist files are useful for DMCs, which can retrieve the playlist, hand it to a DMR and then exit. The DMR can continue to play the playlist even though the DMC has exited as it has the playlist file which contains the URLs. A container may have multiple resources, for example if it supports multiple playlist formats. GetCompatibleResources could be called, for example, by a DMC using the protocol info of a renderer. The method will then return the resource compatible with the renderer if such a resource exists.

Recommended Usage

All of the list and search functions supported by dLeyna-server'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.

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 capable of displaying only 30 items at a time. This will increase the memory requirements of the client and reduce its responsiveness because it must wait until all 2000 items have been received, before it can update the UI. Also, if the user locates the item, they are 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 will include all the properties of all the requested objects in the result. However, often the client needs to know only a subset of these properties. A UI that displays results of a search might want to display only the names, and perhaps the dates, of the items that match the search. Once the user has identified the item they are 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 ['*'] would generate a lot more output.

Project: