dLeyna-renderer exposes a separate d-Bus object for each DMR that it detects on the LAN. These objects serve three purposes:
- They allow the client to retrieve information about the DMR, such as its name, the URL of its icon, its manufacturer, the currently playing content, etc.
- They allow the client to manipulate the DMR, that is, to play a given URL, to play, pause, and stop, etc.
- They can be used to implement two-box push.
Each renderer object exposes four separate interfaces:
The com.intel.dLeynaRenderer.RendererDevice interface contains properties that provide clients with information about DMRs.
The com.intel.dLeynaRenderer.RendererDevice interface exposes information about the DMR through a number of d-Bus properties. These properties are described below:
|DeviceType||s||m||The UPnP type of the device, such as, urn:schemas-upnp-org:device:MediaRenderer:1|
|UDN||s||m||The Unique Device Name of the renderer.|
|FriendlyName||s||m||The friendly name of the renderer.|
|IconURL||s||o||A URL pointing to an icon that graphically identifies the renderer.|
|Manufacturer||s||m||A string identifying the manufacturer of the renderer.|
|ManufacturerUrl||s||o||A URL pointing to the renderer's web site.|
|ModelDescription||s||o||A description of the renderer.|
|ModelName||s||m||The model name of the renderer.|
|ModelNumber||s||o||The renderer's version number.|
|SerialNumber||s||o||The renderer's serial number.|
|PresentationURL||s||o||The presentation URL of the renderer, that is, a link to its HTML management interface.|
|ProtocolInfo||s||m||A string that identifies all of the file formats and network protocol combinations that the renderer supports.|
(* where m/o indicates whether the property is optional or mandatory)
The idea behind the ProtocolInfo property is a little complicated and requires further discussion. It is a comma separated list of protocol info values. Each protocol info value consists of four fields separated by colons. Unfortunately, the format is too complex to describe here. The reader is referred to the UPnP Connection Manager Service Template document and the DLNA Guidelines, 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.
The ProtocolInfo property identifies the types of URLs the renderer is capable of playing. The example value given above indicates that the renderer is capable of retrieving (through HTTP) and playing/displaying audio MP4 and JPEG files. Now, the astute among you might notice that the information provided by the ProtocolInfo property is already available from the standard MPRIS SupportedMimeTypes and SupportedUriSchemes properties. This is true, however, ProtocolInfo is still useful because its value is specifically formatted to make it easy to write a certain type of application, called a Digital Media Controller (DMC).
When you write a DMC, you instruct a DMR to play a media file exposed by a Digital Media Server (DMS). DMSs often publish the same piece of media content in a number of formats, exposing a separate URL for each format. The DMC can use the ProtocolInfo of a particular renderer, to determine which of the many formats is most suitable for the renderer and having done this to determine which URL to use. If the DMC uses dLeyna-server to browse the contents of DMSs, it can achieve this simply by identifying the dLeyna-server d-Bus object of the file it wishes to play, and then invoking this object's GetCompatibleResource method, passing the renderer's ProtocolInfo string as a parameter. This method will then return the most suitable URL for the renderer.
The com.intel.dLeynaRenderer.RendererDevice interface provides the following methods:
|Cancel() -> void||Cancels all outstanding requests a client has issued to the device. dLeyna-renderer maintains one task queue per client per DMR. Commands are placed into the relevant queue when received by dLeyna-renderer. All commands in a given queue are executed sequentially. This means that a given client can issue as many parallel commands to a given renderer as it likes, but these commands will be executed one after the other. On the other hand, commands issued to other renderer or issued to the same renderer by different clients are processed in parallel by dLeyna-renderer. Calling the Cancel function for a com.intel.dLeynaRenderer.RendererDevice object cancels all the outstanding commands the client has issued on this object. All such commands will fail with an appropriate error.|
|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. This is a helper function for client applications as it prevents them from having to issue a HTTP request to retrieve the icon. The URL is still available so they are free to continue doing so if they wish. New in version 0.0.2.|
This interface is part of the MPRIS standard and is documented in the MPRIS D-Bus Interface Specification document. That document describes the interface well, so this section will focus on the peculiarities of dLeyna-renderer's implementation of this interface, rather than the interface itself.
The main points of interest are:
- The methods Raise and Quit are implemented, but they do nothing. The CanRaise and CanQuit properties necessarily return false.
- The property HasTrackList is always set to false. This is because track lists are not yet implemented. Hopefully, this will change in the future.
- The property CanSetFullscreen is always set to false. Fullscreen is not implemented.
- The DesktopEntry property is not implemented.
- PropertiesChanged signals are emitted via the org.freedesktop.DBus.Properties interface of a renderer object instance when org.mpris.MediaPlayer2.Player interface properties value change.
Like org.mpris.MediaPlayer2, org.mpris.MediaPlayer2.Player is a standard MPRIS interface and is already documented in the MPRIS specification. Consequently, this section will describe only the peculiarities of dLeyna-renderer's implementation of this interface. The main points of interest are noted below:
- The LoopStatus property is not implemented.
- The Shuffle property is not implemented.
- The Seek signal is not implemented yet.
- The first parameter to SetPosition is ignored, and any valid d-Bus path can be specified as its value.
In addition to these restrictions, dLeyna-renderer's implementation of org.mpris.MediaPlayer2.Player exposes a number of additional properties that are not part of the MPRIS specification. These properties are described in the table below.
|TransportPlaySpeeds||ad||m||An array of doubles that represent the play speeds supported by the renderer. This property allows clients to set the Rate property with a value that will be accepted by the DMR.|
|CurrentTrack||u||m||The the sequence number of the currently selected track.|
|NumberOfTracks||u||m||The number of tracks in the currently selected media.|
|Mute||b||o||The mute setting of the master audio channel. New in version 0.0.2.|
dLeyna-renderer also introduces two new method to org.mpris.MediaPlayer2.Player.
|GotoTrack(u TrackNumber) -> void||Performs a seek operation to the specified track number.|
|OpenUriEx(s Uri, s Metadata) -> void||Identical to the org.mpris.MediaPlayer2.Player OpenUri method with one exception. OpenUriEx takes an additional parameter, Metadata, to specify the DIDL-Lite XML description of the item to be opened. New in version 0.0.2.|
org.mpris.MediaPlayer2.TrackList and org.mpris.MediaPlayer2.Playlists
Are not yet implemented.
DMRs participate in two different DLNA use cases: three-box system and two-box push. In the three-box system, a DMC instructs a DMR to play a URL hosted by a DMS. In two-box push, an application pushes content it has created or downloaded directly to a renderer. In two-box push, the DMS is not involved at all and this presents a problem because DMRs do not really support the concept of push. Rather than pushing files to a DMR, the client passes it a URL and then instructs the DMR to pull the content from the URL. For this to work, a web server must be running somewhere to host the URL. In the three-box system, the role of the web server is played by the DMS. Unfortunately, as we have seen, in two-box push there is no DMS. So, who will host the content to be pushed?
Conceptually, each application that wishes to push a file to a DMR could start its own web server where it could temporarily host the file to be pushed. However, this is complicated for application developers and also wasteful of system resources. Potentially, every application that can create download content can push this content to DMRs. Because these applications can legitimately run simultaneously, having them run their own web servers would consume unnecessary system resources.
dLeyna-renderer solves these problems by providing both a web server and simple APIs that can be used by clients to host files on this server. Because only one instance of dLeyna-renderer runs at any one time (well, currently only one can run per user session), we avoid the proliferation of web servers. These push APIs are provided by the com.intel.dLeynaRenderer.PushHost interface, which is implemented by all renderer objects. com.intel.dLeynaRenderer.PushHost contains two methods, which are described below:
|HostFile(s path) -> s||Hosts a file on dLeyna-renderer's web server. The parameter path should be a full path to the local file to be hosted, such as /home/user/Podcasts/pod.mp3. The value returned is the URL of the newly hosted file.|
|RemoveFile(s path) -> void||Stops hosting the file whose full path is passed as a parameter for this function.|
dLeyna-renderer runs a web server only when files are being hosted. Once all clients have stopped hosting files, either by calling RemoveFile or by exiting, dLeyna-renderer will shut down its web server. Actually, dLeyna-renderer may run more than one web server if multiple DMRs are accessed over different interfaces. When a client chooses to host a file for a given renderer, dLeyna-renderer checks to see if a web server is already running on the interface through which this renderer is accessible. If it is not, it starts a new web server. It follows that if clients try to host multiple files for multiple renderers running on different interfaces, dLeyna-renderer may actually run multiple servers. However, it will only run one server per interface, and the server will be shut down as soon as it no longer has any files to host.