Samsung Electronics logo

Samsung Web API: DeviceDiscovery

© 2013 Samsung Electronics Co., Ltd. All rights reserved.

Introduction

This API allows developers to get a list of discovered AllShare devices with a specified ID, domain and NIC. It also includes provisions for obtaining device discovery update notification.

Table of Contents

Summary of Interfaces and Methods

Interface Method
DeviceDiscoveryCallback void ondeviceadded(Device device)
void ondeviceremoved(Device device)
Icon
DeviceFinder Device? getDevice(DeviceType deviceType, DeviceId id, SubFeatureType? subFeatureType)
DeviceArray getDeviceList(DeviceType deviceType)
DeviceArray getDeviceListByDomain(DeviceType deviceType, DeviceDomain domain)
DeviceArray getDeviceListByNIC(DeviceType deviceType, DOMString nic)
void refresh()
long addDeviceDiscoveryListener(DeviceDiscoveryCallback deviceDiscoveryCallback)
void removeDeviceDiscoveryListener(long deviceDiscoveryListener)
Device

1. Type Definitions

1.1. DeviceId

The device identifier 

    typedef DOMString DeviceId;

1.2. DeviceArray

Array of Devices 

    typedef sequence<DeviceDevice> DeviceArray;

1.3. IconArray

Array of Icons 

    typedef sequence<Icon> IconArray;

1.4. DeviceType

Specifies the device type which can be discovered. 

    enum DeviceType { "AVPLAYER", 
                                "IMAGEVIEWER", 
                                "FILERECEIVER",
                                "MEDIAPROVIDER",
                                "TVCONTROLLER",
                                "UNKNOWN" };
  • AVPLAYER: Audio and video player
  • IMAGEVIEWER: Image viewer
  • FILERECEIVER: File receiver
  • MEDIAPROVIDER: Media provider
  • TVCONTROLLER: TV controller
  • UNKNOWN: Unknown device type

1.5. SubFeatureType

Specifies the sub feature type for a specific device type. 

    enum SubFeatureType  {"VIEWCONTROLLER"};
  • VIEWCONTROLLER: View controller feature belongs to Image viewer

1.6. DeviceDomain

Specifies the network domain in which the device is located. 

    enum DeviceDomain { "LOCAL_NETWORK", 
                                    "MY_DEVICE", 
                                    "REMOTE_NETWORK", 
                                    "UNKNOWN" };
  • LOCAL_NETWORK: Located in local network area
  • MY_DEVICE: Located in my device
  • REMOTE_NETWORK: Located in internet area
  • UNKNOWN: Located in unknown area

2. Interfaces

2.1. DeviceDiscoveryCallback

Provides a generic callback for notification about device discovery events 

    [Callback, NoInterfaceObject] interface DeviceDiscoveryCallback {
        
        void ondeviceadded(DeviceDevice device); 
        
        void ondeviceremoved(DeviceDevice device); 
    };

METHODS

ondeviceadded

Invoked when a new device has appeared in the network.

Signature
void ondeviceadded(Device device);
Parameters
  • device
    • Optional: No.
    • Nullable: No.
    • Type: Device.
    • Description: A newly discovered device.

ondeviceremoved

Invoked when a device is going to disappear from the network

Signature
void ondeviceremoved(Device device);
Parameters
  • device
    • Optional: No.
    • Nullable: No.
    • Type: Device.
    • Description: Device which is going to disappear.

2.2. Icon

Represents the icon information. 

    [NoInterfaceObject] interface Icon {
    
        readonly attribute long depth;
        
        readonly attribute long height;
        
        readonly attribute long width;
        
        readonly attribute DOMString mimeType;
        
        readonly attribute DOMString iconUri;
    };

ATTRIBUTES

readonly long depth

Color depth of the icon in bits per pixel.

This attribute is read-only.

readonly long height

Height of the icon

This attribute is read-only.

readonly long width

Width of the icon

This attribute is read-only.

readonly DOMString mimeType

MIME type of the icon

This attribute is read-only.

readonly DOMString iconUri

Uri of the icon

This attribute is read-only.

2.3. DeviceFinder

Provides methods for finding AllShare devices. 

    [NoInterfaceObject] interface DeviceFinder {

        DeviceDevice? getDevice(DeviceType deviceType,
                         DeviceId id, 
                         optional SubFeatureType? subFeatureType);

        DeviceArrayDeviceArray getDeviceList(DeviceType deviceType);
        
        DeviceArrayDeviceArray getDeviceListByDomain(DeviceType deviceType,
                               DeviceDomain domain);
        
        DeviceArrayDeviceArray getDeviceListByNIC(DeviceType deviceType, 
                               DOMString nic);
        
        
        void refresh();
        
        long addDeviceDiscoveryListener(DeviceDiscoveryCallback deviceDiscoveryCallback);
        
        void removeDeviceDiscoveryListener(long deviceDiscoveryListener);
    };

METHODS

getDevice

Provides a device with a specified device ID and device type.

Signature
Device? getDevice(DeviceType deviceType, DeviceId id, optional SubFeatureType? subFeatureType);

In case of retrieving sub features such as MediaReceiver or ViewController, the device ID with the device type such MediaProvider or ImageViewer and the proper SubFeatureType will be used.

If no device has been discovered, then null will be returned.

Parameters
  • deviceType
    • Optional: No.
    • Nullable: No.
    • Type: DeviceType.
    • Description: Specifies type of device
  • id
    • Optional: No.
    • Nullable: No.
    • Type: DeviceId.
    • Description: Specifies device id
  • subFeatureType
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SubFeatureType.
    • Description:
Return value
Specified device object
Exceptions
  • WebAPIException:

    with error type "UnknownError", In any other error case.

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

    with error type "InvalidValuesError", if the deviceType value does NOT have a subFeatureType value.

    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 obtained serviceProvider. For further details, see the creatServiceProvider(..).
 var deviceId;           // it is assumed that an avplayer's device ID has already been determined
 var imageViewerId;  // it is assumed that an imageviewer's device ID has already been determined
 
 try {
     var deviceFinder = serviceProvider.getDeviceFinder();
    // get AV player device object
     var device = deviceFinder.getDevice("AVPLAYER", deviceId);

    // get view controller object with Image Viewer device Id.
    var viewControllerObj = deviceFinder.getDevice("IMAGEVIEWER", imageViewerId, "VIEWCONTROLLER");

     // Print out the device's ID
     console.log(device.id);
     
 } catch(e) {
      console.log(e.name);
 }

getDeviceList

Provides a list of discovered devices with specified device types.

Signature
DeviceArray getDeviceList(DeviceType deviceType);

If no devices of given device type have been discovered, then the empty list will be returned.

Parameters
  • deviceType
    • Optional: No.
    • Nullable: No.
    • Type: DeviceType.
    • Description: Specifies device's type
Return value
DeviceArray Specified devices array
Exceptions
  • WebAPIException:

    with error type "UnknownError", In any other error case.

    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 obtained serviceProvider. For further details,  see the createServiceProvider() or getServiceProvider().
 
 try {
     var deviceFinder = serviceProvider.getDeviceFinder();
     var devices = deviceFinder.getDevices("AVPLAYER");

     // Print out how many AV player devices are available
     console.log(devices.length);
     
 } catch(e) {
      console.log(e.name);
 }

getDeviceListByDomain

Provides a list of discovered devices with specified device type within specified network domain.

Signature
DeviceArray getDeviceListByDomain(DeviceType deviceType, DeviceDomain domain);

If no devices of given device type and given domain have been discovered, then an empty list will be returned.

Parameters
  • deviceType
    • Optional: No.
    • Nullable: No.
    • Type: DeviceType.
    • Description: Provides types of devices specified by their domains.
  • domain
    • Optional: No.
    • Nullable: No.
    • Type: DeviceDomain.
    • Description: Specifies device's domain
Return value
DeviceArray Specified devices array
Exceptions
  • WebAPIException:

    with error type "UnknownError", In any other error case.

    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 have obtained a serviceProvider object. For further details, see createServiceProvider() or getServiceProvider().
 
 try {
     var deviceFinder = serviceProvider.getDeviceFinder();
     var devices = deviceFinder.getDevicesByDomain("AVPLAYER", "LOCAL_NETWORK");

     // Display the number of available AV player devices on local network
     console.log(devices.length);
     
 } catch(e) {
      console.log(e.name);
 }

getDeviceListByNIC

Provides a list of discovered devices with specified types within specified network interface controllers (NICs).

Signature
DeviceArray getDeviceListByNIC(DeviceType deviceType, DOMString nic);

If no devices of given device type and given NIC have been discovered, then an empty list will be returned.

Parameters
  • deviceType
    • Optional: No.
    • Nullable: No.
    • Type: DeviceType.
    • Description: Specifies device's type
  • nic
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The name of the NIC communicating with the device
Return value
DeviceArray Specified devices array
Exceptions
  • WebAPIException:

    with error type "UnknownError", In any other error case.

    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 createServiceProvider() or getServiceProvider().
 
 try {
     var deviceFinder = serviceProvider.getDeviceFinder();
     var devices = deviceFinder.getDevicesByNIC("AVPLAYER", "Wireless LAN");

     // Display the number of AV player devices available on the wireless LAN
     console.log(devices.length);
     
 } catch(e) {
      console.log(e.name);
 }

refresh

Refreshes the list of devices on the network.

Signature
void refresh();
Exceptions
  • WebAPIException:

    with error type "UnknownError", In any other error case.

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

Code example
 
 var serviceProvider; // it is assumed that you obtained serviceProvider. For further details, see createServiceProvider() or getServiceProvider().
 
 try {
     var deviceFinder = serviceProvider.getDeviceFinder();
   
    var providers = deviceFinder.getDevices("MEDIAPROVIDER");
    if (providers.length == 0) {
         // Refreshes the device list and retrieves the provider list again.  
        deviceFinder.refresh();
        providers = deviceFinder.getDevices("MEDIAPROVIDER");
    }
 } catch(e) {
      console.log(e.name);
 }

addDeviceDiscoveryListener

Registers device discovery event listener.

Signature
long addDeviceDiscoveryListener(DeviceDiscoveryCallback deviceDiscoveryCallback);
Parameters
  • deviceDiscoveryCallback
    • Optional: No.
    • Nullable: No.
    • Type: DeviceDiscoveryCallback.
    • Description: Callback function called if the event occurred.
Return value
long Event listener id
Exceptions
  • WebAPIException:

    with error type "UnknownError", In any other error case.

    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 createServiceProvider() or getServiceProvider().
 
 var monitoringCB = {
     ondeviceadded : function (device) { console.log("new device is appeared :" + device.name); },
     ondeviceremoved : function (device) { console.log("a device is disappeared :" + device.name); }
     } 

 try {
     var listenerId = serviceProvider.getDeviceFinder().addDeviceDiscoveryListener(monitoringCB);
     
 } catch(e) {
      console.log(e.name);
 }

removeDeviceDiscoveryListener

Clears device discovery event listener

Signature
void removeDeviceDiscoveryListener(long deviceDiscoveryListener);
Parameters
  • deviceDiscoveryListener
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Event listener id
Exceptions
  • WebAPIException:

    with error type "UnknownError", In any other error case.

    with error type "InvalidValuesError", if argument is invalid.

    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 listenerId; // it is assumed that this listener ID was returned from addDeviceDiscoveryListener(). 
 var monitoringCB = {
     ondeviceadded : function (device) { console.log("new device is appeared :" + device.name); },
     ondeviceremoved : function (device) { console.log("a device is disappeared :" + device.name); }
     } 

 try {
     var listenerId = serviceProvider.getDeviceFinder().addDeviceDiscoveryListener(monitoringCB);
     
 } catch(e) {
      console.log(e.name);
 }

2.4. Device

Provides the information about a device. 

    [NoInterfaceObject] interface Device {
        
        readonly attribute DeviceId id;
        
        readonly attribute DeviceDomain deviceDomain;
        
        readonly attribute DeviceType deviceType;
        
        readonly attribute IconArray iconArray;
        
        readonly attribute DOMString ipAddress;
        
        readonly attribute DOMString? modelName;
        
        readonly attribute DOMString name;
        
        readonly attribute DOMString nic;
    };

For retrieving a device object, see the getDevice(), getDevices(), getDeviceByDomain() or getDeviceByNIC().

ATTRIBUTES

readonly DeviceId id

Specifies the unique ID of the device.

This attribute is read-only.

readonly DeviceDomain deviceDomain

Specifies the device domain

This attribute is read-only.

readonly DeviceType deviceType

Specifies the device type

This attribute is read-only.

readonly IconArray iconArray

Specifies icons associated with the device

This attribute is read-only.

readonly DOMString ipAddress

Specifies the device IPv4 adress

This attribute is read-only.

readonly DOMString? modelName

Specifies the device model name.

This attribute is read-only.

readonly DOMString name

Specifies the device name

This attribute is read-only.

readonly DOMString nic

Specified NIC (Network Interface Controller) name of the device

This attribute is read-only.

3. Full WebIDL 

module DeviceDiscovery {    

    typedef DOMString DeviceId;

    typedef sequence<DeviceDevice> DeviceArray;
    
    typedef sequence<Icon> IconArray;

    enum DeviceType { "AVPLAYER", 
                                "IMAGEVIEWER", 
                                "FILERECEIVER",
                                "MEDIAPROVIDER",
                                "TVCONTROLLER",
                                "UNKNOWN" };

    
    enum SubFeatureType  {"VIEWCONTROLLER"};

    
    enum DeviceDomain { "LOCAL_NETWORK", 
                                    "MY_DEVICE", 
                                    "REMOTE_NETWORK", 
                                    "UNKNOWN" };
    
    [Callback, NoInterfaceObject] interface DeviceDiscoveryCallback {
        
        void ondeviceadded(DeviceDevice device); 
        
        void ondeviceremoved(DeviceDevice device); 
    };
    
    [NoInterfaceObject] interface Icon {
    
        readonly attribute long depth;
        
        readonly attribute long height;
        
        readonly attribute long width;
        
        readonly attribute DOMString mimeType;
        
        readonly attribute DOMString iconUri;
    };
    
    [NoInterfaceObject] interface DeviceFinder {

        DeviceDevice? getDevice(DeviceType deviceType,
                         DeviceId id, 
                         optional SubFeatureType? subFeatureType);

        DeviceArrayDeviceArray getDeviceList(DeviceType deviceType);
        
        DeviceArrayDeviceArray getDeviceListByDomain(DeviceType deviceType,
                               DeviceDomain domain);
        
        DeviceArrayDeviceArray getDeviceListByNIC(DeviceType deviceType, 
                               DOMString nic);
        
        
        void refresh();
        
        long addDeviceDiscoveryListener(DeviceDiscoveryCallback deviceDiscoveryCallback);
        
        void removeDeviceDiscoveryListener(long deviceDiscoveryListener);
    };

    [NoInterfaceObject] interface Device {
        
        readonly attribute DeviceId id;
        
        readonly attribute DeviceDomain deviceDomain;
        
        readonly attribute DeviceType deviceType;
        
        readonly attribute IconArray iconArray;
        
        readonly attribute DOMString ipAddress;
        
        readonly attribute DOMString? modelName;
        
        readonly attribute DOMString name;
        
        readonly attribute DOMString nic;
    };
};