Bondi logo

The Bondi dlna Module - Version 1.5

February 2010

Authors

© 2009-2010 OMTP Ltd. All rights reserved. OMTP and OMTP BONDI are registered trademarks of OMTP Ltd.

Abstract

Provides access to DLNA services

Table of Contents

Summary of Methods

Interface Method
DlnaError
DlnaDevice
DlnaGetVolumeSuccessCallback void onSuccess(unsigned short volume)
DlnaObject
DlnaObjectSelectSuccessCallback void onSuccess(DlnaPlaybackObject playbackObject)
DlnaSuccessCallback void onSuccess()
DlnaErrorCallback void onError(DlnaError error)
DlnaGetPositionSuccessCallback void onSuccess(DOMString position)
DlnaServer boolean registerServerListener(DlnaServerListener listener)
void unregisterServerListener(DlnaServerListener listener)
DlnaDeviceListener void deviceAdded(DlnaDevice device)
void deviceRemoved(DlnaDevice device)
DlnaServerListener void mediaObjectsAdded()
void mediaObjectsRemoved()
void mediaObjectsUpdated()
void sortCapabilitiesReady()
void searchCapabilitiesReady()
DlnaMediaObject
DlnaBrowseSuccessCallback void onSuccess(unsigned long startOffset, unsigned long totalCount, DlnaObjectArray mediaObjects)

1. Introduction

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.

1.2. Features

This is the list of URIs used to declare this API's features, for use in bondi.requestFeature. For each URL, the list of functions covered is provided.

http://bondi.omtp.org/api/dlna.discover

Enables discovery of the devices and medias in the local network

Device capabilities:

  • dlna.discover
http://bondi.omtp.org/api/dlna.render

Enables rendering of the medias in the local network on DLNA renderer (DMR)

Device capabilities:

  • dlna.render

1.3. Device capabilities

dlna.discover

Discovery of the DLNA devices and medias

dlna.render

Rendering of the DLNA media on DMR

2. Type Definitions

2.1. DlnaObjectArray

Array of DLNA objects: media containers and media files. 

        typedef sequence<DlnaObject> DlnaObjectArray;

2.2. DlnaRendererArray

Array of DLNA renderers (DMR). 

        typedef sequence<DlnaRenderer> DlnaRendererArray;

2.3. DlnaServerArray

Array of DLNA servers (DMS). 

        typedef sequence<DlnaServer> DlnaServerArray;

3. Interfaces

3.1. DlnaError

DLNA Errors 

        interface DlnaError : GenericError {

                const unsigned short NO_SELECTION_ERROR = 1;
        };

Constants

unsigned short NO_SELECTION_ERROR

No media was selected for playback

3.2. DlnaDevice

Base interface for DLNA devices (renderer and server). 

         interface DlnaDevice {


                const unsigned short DLNA_DEVICE_TYPE_RENDERER = 0;


                const unsigned short DLNA_DEVICE_TYPE_SERVER = 1;
        

                readonly attribute unsigned short deviceType;


                readonly attribute DOMString name;
        };

Constants

unsigned short DLNA_DEVICE_TYPE_RENDERER

Constant used to identify the type of DLNA device as a renderer.

unsigned short DLNA_DEVICE_TYPE_SERVER

Constant used to identify the type of DLNA device as a server.

Attributes

readonly unsigned short deviceType

Indicates the type of device (renderer or server)

Code example
        if(deviceType == DLNA_DEVICE_TYPE_SERVER) {
                // this is a DLNA server
        }
readonly DOMString name

Advertised name of the device

Code example
        document.getElementById("servername").innerHTML = name;

3.3. DlnaGetVolumeSuccessCallback

DLNA DlnaRender.getVolume specific success callback. 

        [Callback=FunctionOnly, NoInterfaceObject] interface DlnaGetVolumeSuccessCallback {

                void onSuccess(in unsigned short volume);
        };

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.

Methods

onSuccess

Method invoked when the asynchronous call completes succesfully

Signature
void onSuccess(in unsigned short volume);
Parameters
  • volume: The volume value that was requested with DlnaRenderer.getVolumen method (0-100%).

3.5. DlnaObject

Base interface for media container and media file. 

        interface DlnaObject {


                readonly attribute unsigned short objectType;
        };

Attributes

readonly unsigned short objectType

Indicates the type of object (container or media file)

Code example
        if(objectType == DLNA_OBJECT_TYPE_CONTAINER) {
                // this is a container
        }

3.6. DlnaObjectSelectSuccessCallback

DLNA DlnaController.select specific success callback. 

        [Callback=FunctionOnly, NoInterfaceObject] interface DlnaObjectSelectSuccessCallback {


                void onSuccess(in DlnaPlaybackObject playbackObject);
        };

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.

Methods

onSuccess

Method invoked when the asynchronous call to DlnaController.select completes successfully.

Signature
void onSuccess(in DlnaPlaybackObject playbackObject);
Parameters
  • playbackObject: The PlaybackObject that was requested with DlnaController.select() method.

3.7. DlnaSuccessCallback

DLNA specific success callback. 

        [Callback=FunctionOnly, NoInterfaceObject] interface DlnaSuccessCallback {


                void onSuccess();
        };

This callback interface specifies a generic success callback for DLNA APIs.

Methods

onSuccess

Method invoked when the asynchronous call completes successfully.

Signature
void onSuccess();

3.8. DlnaErrorCallback

DLNA specific error callback. 

        [Callback=FunctionOnly, NoInterfaceObject] interface DlnaErrorCallback {


                void onError(in DlnaError error);
        };

This callback interface specifies a generic error callback for DLNA APIs.

Methods

onError

Method invoked when the asynchronous call fails.

Signature
void onError(in DlnaError error);
Parameters
  • error: Error code providing more information about the reason of the failure.

3.9. DlnaGetPositionSuccessCallback

DLNA DlnaPlaybackObject.getPosition specific success callback. 

        [Callback=FunctionOnly, NoInterfaceObject] interface DlnaGetPositionSuccessCallback {


                void onSuccess(in DOMString position);
        };

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.

Methods

onSuccess

Method invoked when the asynchronous call to DlnaPlaybackObject.getPosition succeeds.

Signature
void onSuccess(in DOMString position);
Parameters
  • position: Playback position in HH:MM:SS.msec format relative to the beginning of the media.

3.10. DlnaServer

DLNA Server (DMS) interface. 

        interface DlnaServer : DlnaDevice {


                readonly attribute DlnaMediaContainer root;


                readonly attribute DOMString sortCapabilities;


                readonly attribute DOMString searchCapabilities;


                boolean registerServerListener(in DlnaServerListener listener)
            raises(SecurityError, DeviceAPIError);


                void unregisterServerListener(in DlnaServerListener listener)
            raises(SecurityError, DeviceAPIError);
        };

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.

Attributes

readonly DlnaMediaContainer root

Root media container (folder) of the server. Browsing of the data on the DMS starts here.

readonly DOMString sortCapabilities

Sort capabilities of the DLNA server (DMS)

Code example
   alert(server.sortCapabilities);//should display something like "upnp:foreignMetadata::fmBody::fmURI"
readonly DOMString searchCapabilities

Search capabilities of the DLNA server (DMS)

Code example
   alert(server.searchCapabilities);//should display something like "upnp:foreignMetadata::fmBody::fmURI"

Methods

registerServerListener

This method registers the listener for server events

Signature
boolean registerServerListener(in DlnaServerListener listener);
Parameters
  • listener: Listener
Return value
true if successful
Exceptions
  • SecurityError:
  • DeviceAPIError:
unregisterServerListener

This method unregisters the listener for server events

Signature
void unregisterServerListener(in DlnaServerListener listener);
Parameters
  • listener: Listener
Exceptions
  • SecurityError:
  • DeviceAPIError:

3.13. DlnaDeviceListener

Listener for the generic DLNA device events 

        [Callback] interface DlnaDeviceListener {


                void deviceAdded(in DlnaDevice device);


                void deviceRemoved(in DlnaDevice device);
        };

Methods

deviceAdded

Called when a new device advertised itself

Signature
void deviceAdded(in DlnaDevice device);
Parameters
  • device: DLNA device that was added.
deviceRemoved

Called when a device was removed from the network

Signature
void deviceRemoved(in DlnaDevice device);
Parameters
  • device: DLNA device that was removed.

3.14. DlnaServerListener

Listener for the server events 

        [Callback] interface DlnaServerListener { 


                void mediaObjectsAdded();


                void mediaObjectsRemoved();


                void mediaObjectsUpdated();


                void sortCapabilitiesReady();


                void searchCapabilitiesReady();
        };

Methods

mediaObjectsAdded

Called when a new media object was added to the server

Signature
void mediaObjectsAdded();
mediaObjectsRemoved

Called when a media object was removed from the server

Signature
void mediaObjectsRemoved();
mediaObjectsUpdated

Called when a media object was updated on the server

Signature
void mediaObjectsUpdated();
sortCapabilitiesReady

Called when the server's sorting capabilities are ready (sortCapabilities is filled with data)

Signature
void sortCapabilitiesReady();
searchCapabilitiesReady

Called when the server's searching capabilities are ready (searchCapabilities is filled with data)

Signature
void searchCapabilitiesReady();

3.15. DlnaMediaObject

Type of this media file. 

        interface DlnaMediaObject : DlnaObject {


                const unsigned short DLNA_OBJECT_TYPE_CONTAINER = 0;


                const unsigned short DLNA_OBJECT_TYPE_MEDIA = 1;


                readonly attribute DOMString type;


                readonly attribute DOMString id;


                readonly attribute DOMString title;


                readonly attribute Date datetime;


                readonly attribute DOMString url;


                readonly attribute DOMString genre;


                readonly attribute DOMString artist;    
        };
Code example
        alert(media.type); // displays the type of the media file

Constants

unsigned short DLNA_OBJECT_TYPE_CONTAINER

Container object.

unsigned short DLNA_OBJECT_TYPE_MEDIA

Media object.

Attributes

readonly DOMString type

Type of this media file.

Code example
        alert(media.type); // displays the type of the media file
readonly DOMString id

Identifier of this media file. The identifier is local to the DMS.

Code example
        alert(media.id); // displays the identifier of the media file
readonly DOMString title

Title of this media file.

Code example
        alert(media.title); // displays the title of the media file
readonly Date datetime

Date and time associated with this media file.

Code example
        alert(media.datetime); // displays the date and time of the media file
readonly DOMString url

URL that points to this media file.

Code example
        alert(media.url); // displays the URL of the media file
readonly DOMString genre

Genre of this media file.

Code example
        alert(media.genre); // displays the genre of the media file
readonly DOMString artist

Type of this media file.

Code example
        alert(media.type); // displays the type of the media file

3.16. DlnaBrowseSuccessCallback

DLNA DlnaMediaContainer.browser and .search specific success callback. 

        [Callback=FunctionOnly, NoInterfaceObject] interface DlnaBrowseSuccessCallback {

                void onSuccess(in unsigned long startOffset, in unsigned long totalCount, in DlnaObjectArray mediaObjects);
        };

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.

Methods

onSuccess

Method invoked when the asynchronous call completes successfully

Signature
void onSuccess(in unsigned long startOffset, in unsigned long totalCount, in DlnaObjectArray mediaObjects);
Parameters
  • startOffset: The position of the media object in the list of media objects on the server.
  • totalCount: Total number of media objects in the container.
  • mediaObjects: Media objects' metadata retrieved from the server during this execution of the browser or search.