Samsung Electronics logo

Samsung Web API: Provider


Introduction

This API allows developers to share media contents between DLNA devices.

It provides the operations as follows:

  • Browse or search contents which are provided from all available digital media servers (DMS)
  • Download a content from another DMS to my local device.

Table of Contents


Summary of Interfaces and Methods

Interface Method
MediaProviderSuccessCallback void onsuccess(ItemList itemList, boolean endOfItems, DeviceId providerId)
MediaProviderErrorCallback void onerror(WebAPIError error, DeviceId providerId)
MediaProviderEventCallback void oncontentupdated()
MediaReceiverSuccessCallback void onsuccess(long sessionId)
MediaReceiverErrorCallback void onerror(WebAPIError error, long sessionId)
MediaReceiverEventCallback void oncompleted(long sessionId)
void onprogressupdated(long sessionId, long receivedSize, long totalSize)
MediaProvider MediaReceiver getMediaReceiver()
void browse(Item folderItem, unsigned long startIndex, unsigned long requestCount, MediaProviderSuccessCallback browseCallback, MediaProviderErrorCallback? errorCallback, AbstractFilter? browseFilter, SortMode? sortMode)
void search(DOMString keyword, unsigned long startIndex, unsigned long requestCount, MediaProviderSuccessCallback successCallback, MediaProviderErrorCallback? errorCallback, AbstractFilter searchFilter)
long addMediaProviderEventListener(MediaProviderEventCallback eventCallback)
void removeMediaProviderEventListener(long eventCallbackId)
MediaReceiver long receive(Item item, MediaReceiverSuccessCallback successCallback, MediaReceiverErrorCallback? errorCallback, MediaReceiverEventCallback? eventCallback)
void cancel(long sessionId, MediaReceiverSuccessCallback successCallback, MediaReceiverErrorCallback? errorCallback)

1. Type Definitions

1.1. ItemList

Array of Items which are provided from a device on the network.

    typedef sequence<Item> ItemList;

2. Interfaces

2.1. MediaProviderSuccessCallback

Callback invoked when the retrieving operations of a Provider object is completed successfully.

    [Callback=FunctionOnly, NoInterfaceObject] interface MediaProviderSuccessCallback {
    
        void onsuccess(ItemList itemList, 
                       boolean endOfItems, 
                       DeviceId providerId);
    };

METHODS

onsuccess

Callback function for successful retrieve request.

Signature
void onsuccess(ItemList itemList, boolean endOfItems, DeviceId providerId);
Parameters
  • itemList
    • Optional: No.
    • Nullable: No.
    • Type: ItemList.
    • Description: A list of items. If there is no item it will return an empty list.
  • endOfItems
    • Optional: No.
    • Nullable: No.
    • Type: boolean.
    • Description: The end of items flag.
  • providerId
    • Optional: No.
    • Nullable: No.
    • Type: DeviceId.
    • Description: The identifier of the provider device.

2.2. MediaProviderErrorCallback

Generic error callback for provider related operations.

    [Callback=FunctionOnly, NoInterfaceObject] interface MediaProviderErrorCallback {
        
        void onerror(WebAPIError error, 
                     DeviceId providerId);
    };

METHODS

onerror

Callback function invoked when error occurs.

Signature
void onerror(WebAPIError error, DeviceId providerId);
Parameters
  • error
    • Optional: No.
    • Nullable: No.
    • Type: WebAPIError.
    • Description: WebAPIError object which indicates error type and message.
  • providerId
    • Optional: No.
    • Nullable: No.
    • Type: DeviceId.
    • Description: The identifier of the provider device.

2.3. MediaProviderEventCallback

Callback for monitoring the event of the provider device.

    [Callback=FunctionOnly, NoInterfaceObject] interface MediaProviderEventCallback {
        
        void oncontentupdated();
    };

METHODS

oncontentupdated

Method invoked when content in the provider device has been updated.

Signature
void oncontentupdated();

2.4. MediaReceiverSuccessCallback

Generic success callback invoked when the requested operation of a receiver object completes successfully.

    [Callback=FunctionOnly, NoInterfaceObject] interface MediaReceiverSuccessCallback {
        
        void onsuccess(long sessionId);
    };

METHODS

onsuccess

Method invoked when the operation is successful.

Signature
void onsuccess(long sessionId);
Parameters
  • sessionId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The operation session ID returned by receive() API.

2.5. MediaReceiverErrorCallback

Generic error callback which is invoked an error is occurred while receiving a content item.

    [Callback=FunctionOnly, NoInterfaceObject] interface MediaReceiverErrorCallback {
        
        void onerror(WebAPIError error,  long sessionId);
    };

METHODS

onerror

Method invoked when error occurs.

Signature
void onerror(WebAPIError error, long sessionId);
Parameters
  • error
    • Optional: No.
    • Nullable: No.
    • Type: WebAPIError.
    • Description: WebAPIError object which indicates error type and message.
  • sessionId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The operation session ID returned by the receive() API.

2.6. MediaReceiverEventCallback

Callback interface for monitoring the event during data transfer.

    [Callback, NoInterfaceObject] interface MediaReceiverEventCallback {
        
        void oncompleted(long sessionId);
        
        void onprogressupdated(long sessionId,  long receivedSize,  long totalSize);
    
    };

METHODS

oncompleted

Method invoked when the item has been completely downloaded.

Signature
void oncompleted(long sessionId);
Parameters
  • sessionId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The operation session ID returned by the receive() API.

onprogressupdated

Method invoked when the transfer progress is updated.

Signature
void onprogressupdated(long sessionId, long receivedSize, long totalSize);
Parameters
  • sessionId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The operation session ID returned by the receive() API.
  • receivedSize
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Size of the item that has been transferred.
  • totalSize
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Total size of the item.

2.7. MediaProvider

This interface provides a means of sharing media content between devices.

    [NoInterfaceObject] interface MediaProvider : DeviceDevice {
        
        readonly attribute boolean isSearchable;
        
        readonly attribute Item rootFolder;
        
        MediaReceiver getMediaReceiver();
    
        void browse(Item folderItem, 
                    unsigned long startIndex,
                    unsigned long requestCount, 
                    MediaProviderSuccessCallback browseCallback,
                    optional MediaProviderErrorCallback? errorCallback,
                    optional AbstractFilter? browseFilter, 
                    optional SortMode? sortMode
                    );
        
        void search(DOMString keyword,
                    unsigned long startIndex,
                    unsigned long requestCount,
                    MediaProviderSuccessCallback successCallback,
                    optional MediaProviderErrorCallback? errorCallback,
                    optional AbstractFilter searchFilter);
        
        long addMediaProviderEventListener(MediaProviderEventCallback eventCallback);
        
        void removeMediaProviderEventListener(long eventCallbackId);
    
    };

MediaProvider is a specific type of device. Developers can obtain the object by using a method that retrieves devices.

ATTRIBUTES

readonly boolean isSearchable

Specifies whether the provider supports search capability.

This attribute is read-only.

readonly Item rootFolder

Object of the root folder.

This attribute is read-only.

METHODS

getMediaReceiver

Obtains the MediaReceiver object which downloads content from the other media provider.

Signature
MediaReceiver getMediaReceiver();

Some Providers may not have a Receiver, which case the return value should be null. If any error occurs, WebAPIException will be thrown.

Return value
Receiver The object of Receiver.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

Code example
 
 var provider; // it is assumed that a provider object is retrieved properly. For further details, see the getDevice().
 
 try {
    var receiver = provider.getMediaReceiver();
    if (receiver) {
        // Do something with the receiver object.
    }
 } catch (e) {
     console.log(e.name);
 }
 
 

browse

Gets the item list in a folder at the specified starting index and count.

Signature
void browse(Item folderItem, unsigned long startIndex, unsigned long requestCount, MediaProviderSuccessCallback browseCallback, optional MediaProviderErrorCallback? errorCallback, optional AbstractFilter? browseFilter, optional SortMode? sortMode);

The error callback is launched with these error types:

  • NotConnectedServiceError: if the application doesn't connect to AllShare framework.
  • NotFoundError: if the item does not exist.
  • InvalidStateError: if the device or state is invalid or unusable.
  • NetworkNotAvailableError: if the network is not available.
  • TimeOutError: If the request is timeout.
  • InvalidValuesError: If any input parameter contains invalid values.
  • UnknownError: In the case of any other error
Parameters
  • folderItem
    • Optional: No.
    • Nullable: No.
    • Type: Item.
    • Description: The item which represents a folder to be retrieved.
  • startIndex
    • Optional: No.
    • Nullable: No.
    • Type: unsigned long.
    • Description: The starting zero-based offset to enumerate children under the specific item.
  • requestCount
    • Optional: No.
    • Nullable: No.
    • Type: unsigned long.
    • Description: The requested number of entries.
  • browseCallback
    • Optional: No.
    • Nullable: No.
    • Type: MediaProviderSuccessCallback.
    • Description: Success callback invoked when the browse operation is successful; it returns a set of items matching the filter.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: MediaProviderErrorCallback.
    • Description: Generic error callback for provider related operations.
  • browseFilter
    • Optional: Yes.
    • Nullable: Yes.
    • Type: AbstractFilter.
    • Description: Filter applied for the browsing. An AttributeFilter object constructed with ("itemType", null , ItemType[]) can be valid as a parameter.
  • sortMode
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SortMode.
    • Description: Sorting mode to be used for arranging the list of content upon completion of the browsing. Sorting with a title, date, artist and albumTitle as the attribute is only supported on the Tizen Web platform. Other Web platforms will ignore this parameter.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var serviceProvider; // it is assumed that you has obtained a serviceProvider object. For further details,  see the createServiceProvider() or getServiceProvider().

 //Define browse callback
 function browseCB(list, endOfItem, providerId) {
     // the item list can be retrieved here
 }
 
 function errorCB(error, deviceId) {
    console.log(error.message);
 } 
        
 // Define a filter to browse a video type only
 var filter = new webapis.AttributeFilter("itemType", null, {"VIDEO"});

 // Define a sort mode
 var mode = new webapis.SortMode("title", "ASC");
          
 try {
     var providers = serviceProvider.getDeviceFinder().getDevices("MEDIAPROVIDER");
     if (providers.length > 0) {
           // retrieves first DMS from the root folder 
          providers[0].browse(providers[0].rootFolder, 0, 10, browseCB, errorCB, filter, mode);
       }
 } catch(e) {
    console.log(e.message);
  } 
 
 

search

Searches content items with a keyword.

Signature
void search(DOMString keyword, unsigned long startIndex, unsigned long requestCount, MediaProviderSuccessCallback successCallback, optional MediaProviderErrorCallback? errorCallback, optional AbstractFilter searchFilter);

Searching with the value "" (empty string) for the keyword argument will return all available items.

The error callback is launched with these error types:

  • NotConnectedServiceError: if the application doesn't connect to AllShare framework.
  • NotFoundError: if the item does not exist.
  • InvalidStateError: if the device or state is invalid or unusable.
  • NetworkNotAvailableError: if the network is not available.
  • TimeOutError: If the request is timeout.
  • InvalidValuesError: If any input parameter contains invalid values.
  • UnknownError: In the case of any other error
Parameters
  • keyword
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The keyword which will be used for the search.
  • startIndex
    • Optional: No.
    • Nullable: No.
    • Type: unsigned long.
    • Description: The starting zero-based offset to enumerate children under the specific item.
  • requestCount
    • Optional: No.
    • Nullable: No.
    • Type: unsigned long.
    • Description: The requested number of entries.
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: MediaProviderSuccessCallback.
    • Description: Success callback invoked when the search operation is successful; it returns a set of items matching the filter.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: MediaProviderErrorCallback.
    • Description: Generic error callback for provider related operations.
  • searchFilter
    • Optional: Yes.
    • Nullable: No.
    • Type: AbstractFilter.
    • Description: Filter applied to the search result. An AttributeFilter object constructed with ("itemType", null , ItemType[]) can be valid as a parameter.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var serviceProvider; // it is assumed that you has obtained a serviceProvider object. For further details,  see the createServiceProvider() or getServiceProvider().
 var keyword = "foo"; 

 //Define browse callback
 function searchCB(list, endOfItem, providerId){
     // the item list can be retrieved here
 }
 
 function errorCB(error, device){
    console.log(device + " raises " + error);
 } 
        
 // Define a filter to browse a video type only
 var filter = new webapis.AttributeFilter("itemType", null, {"VIDEO"});
          
 try {
     var providers = serviceProvider.getDeviceFinder().getDevices("MEDIAPROVIDER");
     if (providers.length > 0) {
           // search the keyword on the first DMS. 
          providers[0].search(keyword, 0, 40, searchCB, errorCB, filter);
       }
 } catch(e) {
    console.log(e.message);
  } 
 
 

addMediaProviderEventListener

Set the event listener that will monitor the event fired when content is updated.

Signature
long addMediaProviderEventListener(MediaProviderEventCallback eventCallback);
Parameters
  • eventCallback
    • Optional: No.
    • Nullable: No.
    • Type: MediaProviderEventCallback.
    • Description: Callback interface that will capture the event.
Return value
long Identifier for the event listener. It can be used to remove the listener.
Exceptions
  • WebAPIException:

    with error type UnknownError, In the case of any other error

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var provider; // it is assumed that a provider object is retrieved properly. For further details, see the getDevice().
 
 function onContentUpdated() {
     console.log("The contents in this provider is updated. please revisit it.");
 }
 
try {
    var handle = provider.addProviderEventListener(onContentUpdated);
 } catch (e) {
     console.log(e.name);
 }

removeMediaProviderEventListener

Remove the event listener synchronously.

Signature
void removeMediaProviderEventListener(long eventCallbackId);
Parameters
  • eventCallbackId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: ID of the event listener returned by addProviderEventListener.
Exceptions
  • WebAPIException:

    with error type UnknownError, any other error case.

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var provider; // it is assumed that a DMS has been retrieved properly. For further details, see the getDevice().
 var handle; // it is assumed that an event handler has been registered properly.
 
 function onContentUpdated() {
     console.log("The contents in this provider is updated. please revisit it.");
 }
 
try {
    var handle = provider.removeProviderEventListener(handle);
 } catch (e) {
     console.log(e.name);
 }
       

2.8. MediaReceiver

Interface provides a means to download a media content from another media provider.

    [NoInterfaceObject] interface MediaReceiver {

        readonly attribute DeviceId id;

        long receive(Item item, 
                          MediaReceiverSuccessCallback successCallback, 
                          optional MediaReceiverErrorCallback? errorCallback,
                          optional MediaReceiverEventCallback? eventCallback);
        
        void cancel(long sessionId, 
                         MediaReceiverSuccessCallback successCallback, 
                         optional MediaReceiverErrorCallback? errorCallback);
    };

ATTRIBUTES

readonly DeviceId id

Specifies the unique ID of the receiver.

It will be the same ID of a provider device which provides this receiver.

This attribute is read-only.

METHODS

receive

Download an item from a remote device.

Signature
long receive(Item item, MediaReceiverSuccessCallback successCallback, optional MediaReceiverErrorCallback? errorCallback, optional MediaReceiverEventCallback? eventCallback);

When this API is be invoked, a session ID which is used for monitoring this operation will be returned immediately. The success callback will be invoked when this transfer operation is going to start successfully. The error callback is launched with these error types:

  • NotConnectedServiceError: if the application doesn't connect to AllShare framework.
  • InvalidStateError: if the item is invalid or unusable.
  • NetworkNotAvailableError: if the network is not available.
  • UnknownError: In the case of any other error
Parameters
  • item
    • Optional: No.
    • Nullable: No.
    • Type: Item.
    • Description: Item that will be downloaded by the provider device.
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: MediaReceiverSuccessCallback.
    • Description: Success callback invoked when the response is received from the remote device.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: MediaReceiverErrorCallback.
    • Description: Error callback for transferring items between devices.
  • eventCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: MediaReceiverEventCallback.
    • Description: Callback interface that will capture event occurs while transferring items.
Return value
long Session ID for this receiving operation. It can be used to cancel this operation.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 
 var provider; // it is assumed that a provider object is retrieved properly. For further details, see the getDevice().

 //Define success callback for receive.
 function receiverSCB(sessionId, item) {
         console.log("download: " + item.title);
 }
 
 //Define error callback
 function receiverECB(error, sessionId) {
         console.log(error.message);
 }

 //Define event listener.
 var eventListener = {
         oncompleted: function (item) { console.log("downloading " + item.title + " is completed."); },
         onprogressUpdated: function (item, receivedSize, totalSize) {
             console.log("downloading " + item.title + " is progressing : " + receivedSize + " / " + totalSize); 
         }
 }
 
 //Identify the item to be downloaded.
 var url; // it is assumed that this contains a URL that points to web content.
 var mediaContent = new Item(url);
 
 try {
    var receiver = provider.getReceiver();
    if (receiver) {
        // Download the item.
        var sessionId = receiver.receive(mediaContent, receiverSCB, receiverECB, eventListener);
    }
 } catch (e) {
     console.log(e.name);
 }

 

cancel

Cancel the receiving item from remote device.

Signature
void cancel(long sessionId, MediaReceiverSuccessCallback successCallback, optional MediaReceiverErrorCallback? errorCallback);

The error callback is launched with these error types:

  • NotConnectedServiceError: if the application doesn't connect to AllShare framework.
  • InvalidValuesError: if the session Id to canel is invalid.
  • NetworkNotAvailableError: if the network is not available.
  • UnknownError: In the case of any other error

Parameters
  • sessionId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: handler for the receiving operation to be cancelled.
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: MediaReceiverSuccessCallback.
    • Description: Seccess callback invoked when receive the response from remote device.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: MediaReceiverErrorCallback.
    • Description: Generic error callback for transferring items between devices.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 
 var receiver; // it is assumed that the receiver object has been retrieved properly.
 var handle; // it is assumed that the value contains the return value from the receive() API.

 // Define success callback for cancel.
 function receiverCancelSCB(sessionId, item) {
         console.log("Download is canceled : " + item.title);
 }
 
 //Define error callback
 function receiverECB(error, receiverId) {
         console.log(error.message);
 }
 
 //Cancel downloading the item. Object mediaContent and receiver objects obtained via receive().
 try {
         receiver.cancel(handle, receiverCancelSCB, receiverECB);
 } catch(e) {
         console.log(e.message);
 } 
 
 

3. Full WebIDL

module Provider {

    typedef sequence<Item> ItemList;
   
    [Callback=FunctionOnly, NoInterfaceObject] interface MediaProviderSuccessCallback {
    
        void onsuccess(ItemList itemList, 
                       boolean endOfItems, 
                       DeviceId providerId);
    };
    
    [Callback=FunctionOnly, NoInterfaceObject] interface MediaProviderErrorCallback {
        
        void onerror(WebAPIError error, 
                     DeviceId providerId);
    }; 
    
    [Callback=FunctionOnly, NoInterfaceObject] interface MediaProviderEventCallback {
        
        void oncontentupdated();
    };
    
    [Callback=FunctionOnly, NoInterfaceObject] interface MediaReceiverSuccessCallback {
        
        void onsuccess(long sessionId);
    };
    
    [Callback=FunctionOnly, NoInterfaceObject] interface MediaReceiverErrorCallback {
        
        void onerror(WebAPIError error,  long sessionId);
    };

    [Callback, NoInterfaceObject] interface MediaReceiverEventCallback {
        
        void oncompleted(long sessionId);
        
        void onprogressupdated(long sessionId,  long receivedSize,  long totalSize);
    
    };

    [NoInterfaceObject] interface MediaProvider : DeviceDevice {
        
        readonly attribute boolean isSearchable;
        
        readonly attribute Item rootFolder;
        
        MediaReceiver getMediaReceiver();
    
        void browse(Item folderItem, 
                    unsigned long startIndex,
                    unsigned long requestCount, 
                    MediaProviderSuccessCallback browseCallback,
                    optional MediaProviderErrorCallback? errorCallback,
                    optional AbstractFilter? browseFilter, 
                    optional SortMode? sortMode
                    );
        
        void search(DOMString keyword,
                    unsigned long startIndex,
                    unsigned long requestCount,
                    MediaProviderSuccessCallback successCallback,
                    optional MediaProviderErrorCallback? errorCallback,
                    optional AbstractFilter searchFilter);
        
        long addMediaProviderEventListener(MediaProviderEventCallback eventCallback);
        
        void removeMediaProviderEventListener(long eventCallbackId);
    
    };
    
    [NoInterfaceObject] interface MediaReceiver {

        readonly attribute DeviceId id;

        long receive(Item item, 
                          MediaReceiverSuccessCallback successCallback, 
                          optional MediaReceiverErrorCallback? errorCallback,
                          optional MediaReceiverEventCallback? eventCallback);
        
        void cancel(long sessionId, 
                         MediaReceiverSuccessCallback successCallback, 
                         optional MediaReceiverErrorCallback? errorCallback);
    };
};