/* * Licensed to OMTP Ltd. (OMTP) under one or more contributor license agreements. * See the NOTICE file distributed with this work for additional information regarding * copyright ownership. * * The Reference Implementation (save for such parts of the reference implementation made * available under separate terms and conditions) is made available under the terms of the * Apache License, version 2.0, subject to the condition that any "Works" and "Derivative * Works" used or distributed for commercial purposes must be and remain compliant with the * BONDI specification as promulgated by OMTP in each release. Your implementation of the * Reference Implementation (whether object or source) must maintain these conditions, and * you must notify any recipient of this condition in a conspicuous way. * * You may not use this BONDI Reference Implementation except in compliance with the License. * * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 or at * http://bondi.omtp.org/BONDI-LICENSE-2.0 * */ /** * \brief Provides access to DLNA services * * This API enables discovery of the DLNA devices in the local network, control of the devices. * It shall/could be coupled with the Media Player API for local playback. * * \def-api-feature http://bondi.omtp.org/api/dlna.discover * \brief Enables discovery of the devices and medias in the local network * \device-cap dlna.discover * * \def-device-cap dlna.discover * \brief Discovery of the DLNA devices and medias * * \def-api-feature http://bondi.omtp.org/api/dlna.render * \brief Enables rendering of the medias in the local network on DLNA renderer (DMR) * \device-cap dlna.render * * \def-device-cap dlna.render * \brief Rendering of the DLNA media on DMR * * \author Marcin Hanclik <marcin.hanclik@access-company.com> * \version 1.5 */ module dlna { /** * \brief DLNA Errors */ interface DlnaError : GenericError { /** * \brief No media was selected for playback */ const unsigned short NO_SELECTION_ERROR = 1; }; /** * \brief Base interface for DLNA devices (renderer and server). */ interface DlnaDevice { /** * \brief Constant used to identify the type of DLNA device as a renderer. */ const unsigned short DLNA_DEVICE_TYPE_RENDERER = 0; /** * \brief Constant used to identify the type of DLNA device as a server. */ const unsigned short DLNA_DEVICE_TYPE_SERVER = 1; /** * \brief Indicates the type of device (renderer or server) * * \code * if(deviceType == DLNA_DEVICE_TYPE_SERVER) { * // this is a DLNA server * } * \endcode */ readonly attribute unsigned short deviceType; /** * \brief Advertised name of the device * * \code * document.getElementById("servername").innerHTML = name; * \endcode */ readonly attribute DOMString name; }; /** * \brief DLNA DlnaRender.getVolume specific success callback. * * This callback interface specifies a success callback with a function * taking the volume value as input argument. It is used only with getVolume method * of DlnaRender interface. */ [Callback=FunctionOnly, NoInterfaceObject] interface DlnaGetVolumeSuccessCallback { /** * \brief Method invoked when the asynchronous call completes succesfully * * \param volume The volume value that was requested with DlnaRenderer.getVolumen method (0-100%). */ void onSuccess(in unsigned short volume); }; interface DlnaRenderer : DlnaDevice { /** * \brief Media types (MIME types) supported by the renderer. */ readonly attribute DOMString playCapabilities; /** * \brief This method gets the volume on renderer (DMR) * * \param successCallback called when the volume getting was accomplished successfully * \param errorCallback called if an error occured. * \return PendingOperation enabling the requester to cancel this request. */ PendingOperation getVolume(in DlnaGetVolumeSuccessCallback successCallback, in DlnaErrorCallback errorCallback) raises (SecurityError, DeviceAPIError, DlnaError); /** * \brief This method sets the volume on renderer (DMR) * * \param successCallback called when the volume setting was accomplished successfully * \param errorCallback called if an error occured. * \param volume Volumen value (in %, from 0 to 100) * \return PendingOperation enabling the requester to cancel this request. */ PendingOperation setVolume(in DlnaSuccessCallback successCallback, in DlnaErrorCallback errorCallback, in unsigned short volume) raises (SecurityError, DeviceAPIError, DlnaError); }; /** * \brief Array of DLNA objects: media containers and media files. */ typedef sequence DlnaObjectArray; /** * \brief Array of DLNA renderers (DMR). */ typedef sequence DlnaRendererArray; /** * \brief Array of DLNA servers (DMS). */ typedef sequence DlnaServerArray; /** * \brief Base interface for media container and media file. */ interface DlnaObject { /** * \brief Indicates the type of object (container or media file) * * \code * if(objectType == DLNA_OBJECT_TYPE_CONTAINER) { * // this is a container * } * \endcode */ readonly attribute unsigned short objectType; }; /** * \brief DLNA DlnaController.select specific success callback. * * This callback interface specifies a success callback with a function * taking a PlaybackObject object as input argument. It is used only with select method * of DlnaController interface. */ [Callback=FunctionOnly, NoInterfaceObject] interface DlnaObjectSelectSuccessCallback { /** * \brief Method invoked when the asynchronous call to DlnaController.select completes successfully. * * \param playbackObject The PlaybackObject that was requested with DlnaController.select() method. */ void onSuccess(in DlnaPlaybackObject playbackObject); }; /** * \brief DLNA specific success callback. * * This callback interface specifies a generic success callback for DLNA APIs. */ [Callback=FunctionOnly, NoInterfaceObject] interface DlnaSuccessCallback { /** * \brief Method invoked when the asynchronous call completes successfully. */ void onSuccess(); }; /** * \brief DLNA specific error callback. * * This callback interface specifies a generic error callback for DLNA APIs. */ [Callback=FunctionOnly, NoInterfaceObject] interface DlnaErrorCallback { /** * \brief Method invoked when the asynchronous call fails. * * \param error Error code providing more information about the reason of the failure. */ void onError(in DlnaError error); }; /** * \brief DLNA DlnaPlaybackObject.getPosition specific success callback. * * This callback interface specifies a success callback with a function * taking a PlaybackObject object as input argument. It is used only with select method * of DlnaController interface. */ [Callback=FunctionOnly, NoInterfaceObject] interface DlnaGetPositionSuccessCallback { /** * \brief Method invoked when the asynchronous call to DlnaPlaybackObject.getPosition succeeds. * * \param position Playback position in HH:MM:SS.msec format relative to the beginning of the media. */ void onSuccess(in DOMString position); }; /** * \brief DLNA Server (DMS) interface. * * This interface enable registratior of the listener for server specific events. * It provides access to the root of the file hierarchy within the server * and information about DMS' sort and search capabilities. */ interface DlnaServer : DlnaDevice { /** * \brief Root media container (folder) of the server. Browsing of the data on the DMS starts here. */ readonly attribute DlnaMediaContainer root; /** * \brief Sort capabilities of the DLNA server (DMS) * * \code * alert(server.sortCapabilities);//should display something like "upnp:foreignMetadata::fmBody::fmURI" * \endcode */ readonly attribute DOMString sortCapabilities; /** * \brief Search capabilities of the DLNA server (DMS) * * \code * alert(server.searchCapabilities);//should display something like "upnp:foreignMetadata::fmBody::fmURI" * \endcode */ readonly attribute DOMString searchCapabilities; /** * \brief This method registers the listener for server events * * \param listener Listener * \return true if successful */ boolean registerServerListener(in DlnaServerListener listener) raises(SecurityError, DeviceAPIError); /** * \brief This method unregisters the listener for server events * * \param listener Listener */ void unregisterServerListener(in DlnaServerListener listener) raises(SecurityError, DeviceAPIError); }; interface DlnaController { /** * \brief This method registers the listener for device events * * \param listener Listener * \return true if successful */ boolean registerDeviceListener(in DlnaDeviceListener listener) raises(SecurityError, DeviceAPIError); /** * \brief This method unregisters the listener for device events * * \param listener Listener */ void unregisterDeviceListener(in DlnaDeviceEventListener listener) raises(SecurityError, DeviceAPIError); /** * \brief This method starts the playback of a media object on renderer (DMR) * * \param successCallback called when the selection was accomplished successfully * \param errorCallback called if an error occured. * \param media Media object to be selected for rendering * \param renderer Renderer that is to play the media object * \return PendingOperation enabling the requester to cancel this request. */ PendingOperation select(in DlnaObjectSelectSuccessCallback successCallback, in DlnaErrorCallback errorCallback, in DlnaMediaObject media, in DlnaRenderer renderer) raises (DlnaError); /** * \brief This method determins whether the given renderer is able to playback the given media object * * \param media Media object to be selected for rendering * \param renderer Renderer that is to play the media object * \return true if playback is possible */ boolean isPlayable(in DlnaMediaObject media, in DlnaRenderer renderer) raises (DlnaError); /** * \brief Renderers that are currently available */ readonly attribute DlnaRendererArray currentRenderers; /** * \brief Servers that are currently available */ readonly attribute DlnaServerArray currentServers; }; interface DlnaPlaybackObject { /** * \brief This method starts the playback of a media object on renderer (DMR) * * \param successCallback called when the playback of the media object was started successfully * \param errorCallback called if an error occured. * \param position The position at which the playback should start. * \return PendingOperation enabling the requester to cancel this request. */ PendingOperation play(in DlnaSuccessCallback successCallback, in DlnaErrorCallback errorCallback, [Optional] in DOMString position) raises (SecurityError, DeviceAPIError, DlnaError); /** * \brief This method starts the playback of a media object on renderer (DMR) * * \param successCallback called when the playback of the media object was started successfully * \param errorCallback called if an error occured. * \return PendingOperation enabling the requester to cancel this request. */ PendingOperation stop(in DlnaSuccessCallback successCallback, in DlnaErrorCallback errorCallback) raises (SecurityError, DeviceAPIError, DlnaError); /** * \brief This method starts the playback of a media object on renderer (DMR) * * \param successCallback called when the playback of the media object was started successfully * \param errorCallback called if an error occured. * \return PendingOperation enabling the requester to cancel this request. */ PendingOperation pause(in DlnaSuccessCallback successCallback, in DlnaErrorCallback errorCallback) raises (SecurityError, DeviceAPIError, DlnaError); /** * \brief This method starts the playback of a media object on renderer (DMR) * * \param successCallback called when the playback of the media object was started successfully * \param errorCallback called if an error occured. * \return PendingOperation enabling the requester to cancel this request. */ PendingOperation getPosition(in DlnaGetPositionSuccessCallback successCallback, in DlnaErrorCallback errorCallback) raises (SecurityError, DeviceAPIError, DlnaError); /** * \brief This method starts the playback of a media object on renderer (DMR) * * \param successCallback called when the playback of the media object was started successfully * \param errorCallback called if an error occured. * \param speed The speed of fastforwarding * \return PendingOperation enabling the requester to cancel this request. */ PendingOperation fastForward(in DlnaSuccessCallback successCallback, in DlnaErrorCallback errorCallback, in unsigned long speed) raises (SecurityError, DeviceAPIError, DlnaError); /** * \brief This method starts the playback of a media object on renderer (DMR) * * \param successCallback called when the playback of the media object was started successfully * \param errorCallback called if an error occured. * \param speed The speed of rewinding * \return PendingOperation enabling the requester to cancel this request. */ PendingOperation rewind(in DlnaSuccessCallback successCallback, in DlnaErrorCallback errorCallback, in unsigned long speed) raises (SecurityError, DeviceAPIError, DlnaError); }; /** * \brief Listener for the generic DLNA device events */ [Callback] interface DlnaDeviceListener { /** * \brief Called when a new device advertised itself * * \param device DLNA device that was added. */ void deviceAdded(in DlnaDevice device); /** * \brief Called when a device was removed from the network * * \param device DLNA device that was removed. */ void deviceRemoved(in DlnaDevice device); }; /** * \brief Listener for the server events */ [Callback] interface DlnaServerListener { /** * \brief Called when a new media object was added to the server */ void mediaObjectsAdded(); /** * \brief Called when a media object was removed from the server */ void mediaObjectsRemoved(); /** * \brief Called when a media object was updated on the server */ void mediaObjectsUpdated(); /** * \brief Called when the server's sorting capabilities are ready (sortCapabilities is filled with data) */ void sortCapabilitiesReady(); /** * \brief Called when the server's searching capabilities are ready (searchCapabilities is filled with data) */ void searchCapabilitiesReady(); }; /** * \brief Type of this media file. * * \code * alert(media.type); // displays the type of the media file * \endcode */ interface DlnaMediaObject : DlnaObject { /** * \brief Container object. */ const unsigned short DLNA_OBJECT_TYPE_CONTAINER = 0; /** * \brief Media object. */ const unsigned short DLNA_OBJECT_TYPE_MEDIA = 1; /** * \brief Type of this media file. * * \code * alert(media.type); // displays the type of the media file * \endcode */ readonly attribute DOMString type; /** * \brief Identifier of this media file. The identifier is local to the DMS. * * \code * alert(media.id); // displays the identifier of the media file * \endcode */ readonly attribute DOMString id; /** * \brief Title of this media file. * * \code * alert(media.title); // displays the title of the media file * \endcode */ readonly attribute DOMString title; /** * \brief Date and time associated with this media file. * * \code * alert(media.datetime); // displays the date and time of the media file * \endcode */ readonly attribute Date datetime; /** * \brief URL that points to this media file. * * \code * alert(media.url); // displays the URL of the media file * \endcode */ readonly attribute DOMString url; /** * \brief Genre of this media file. * * \code * alert(media.genre); // displays the genre of the media file * \endcode */ readonly attribute DOMString genre; /** * \brief Type of this media file. * * \code * alert(media.type); // displays the type of the media file * \endcode */ readonly attribute DOMString artist; }; /** * \brief DLNA DlnaMediaContainer.browser and .search specific success callback. * * This callback interface specifies a success callback with a function * taking the start offset, total count (on server) and the array of the media objects as input arguments. * It is used only with browse and search methods of DlnaMediaContainer interface. */ [Callback=FunctionOnly, NoInterfaceObject] interface DlnaBrowseSuccessCallback { /** * \brief Method invoked when the asynchronous call completes successfully * * \param startOffset The position of the media object in the list of media objects on the server. * \param totalCount Total number of media objects in the container. * \param mediaObjects Media objects' metadata retrieved from the server during this execution of the browser or search. */ void onSuccess(in unsigned long startOffset, in unsigned long totalCount, in DlnaObjectArray mediaObjects); }; interface DlnaMediaContainer : DlnaObject { /** * \brief Type of this media file. * * \code * pending = container.browse(successcb, errorcb, 0, 10); * \endcode * * \param successCallback called when the media objects' metadata has been copied. * \param errorCallback called if an error occured. * \param startOffset The position of the media object in the list of media objects on the server. * \param maxCount Maximum number of media objects that can be handled by the client in this request. * \return PendingOperation enabling the requester to cancel this request. */ PendingOperation browse(in DlnaBrowseSuccessCallback successCallback, in DlnaErrorCallback errorCallback, [Optional] in unsigned long startOffset, in unsigned long maxCount); /** * \brief Type of this media file. * * \code * pending = container.search(successcb, errorcb, "dc:title contains 'tenderness'", "upnp:longDescription,dc:creator", "+upnp:artist,-dc:date,+dc:title", 0, 10); * \endcode * * \param successCallback called when the media objects' metadata has been copied. * \param errorCallback called if an error occured. * \param search Search options * \param filter Output filtering options * \param sorting Sorting options * \param startOffset The position of the media object in the list of media objects on the server. * \param maxCount Maximum number of media objects that can be handled by the client in this request. * \return PendingOperation enabling the requester to cancel this request. */ PendingOperation search(in DlnaBrowseSuccessCallback successCallback, in DlnaErrorCallback errorCallback, in DOMString search, in DOMString filter, in DOMString sorting, [Optional] in unsigned long startOffset, in unsigned long maxCount); /** * \brief Media objects that are currently available (i.e. were retrieved) */ readonly attribute DlnaObjectArray currentObjects; /** * \brief Server on which the media container resides. */ readonly attribute DlnaServer server; }; };