top

DeviceDiscovery API

To use Samsung Product API, 

<script type="text/javascript" src="$WEBAPIS/webapis/webapis.js"></script>

Should be loaded in index.html

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

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

Table of Contents

  1. 1. Type Definitions
    1. 1.1. DeviceId
    2. 1.2. DeviceArray
    3. 1.3. IconArray
    4. 1.4. DeviceType
    5. 1.5. DeviceDomain
  2. 2. Interfaces
    1. 2.1. DeviceDiscoveryCallback
    2. 2.2. Icon
    3. 2.3. DeviceFinder
    4. 2.4. Device
  3. 3. Full WebIDL

Summary of Interfaces and Methods

Interface Method
DeviceDiscoveryCallback void ondeviceadded (Device device)
void ondeviceremoved (Device device)
Icon  
DeviceFinder Device? getDevice (DeviceType deviceType, DeviceId id)
DeviceArray getDeviceList (DeviceType deviceType)
void refresh ()
long addDeviceDiscoveryListener (DeviceDiscoveryCallback deviceDiscoveryCallback)
void removeDeviceDiscoveryListener (long deviceDiscoveryListener)
Device  

1. Type Definitions

1.1. DeviceId

The device identifier


  typedef DOMString DeviceId;

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

1.2. DeviceArray

Array of Devices


  typedef sequence<Device> DeviceArray;

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

1.3. IconArray

Array of Icons


  typedef sequence<Icon> IconArray;

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

1.4. DeviceType

Specifies the device type which can be discovered.

  enum DeviceType { "MEDIAPROVIDER",
                    "UNKNOWN" };

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

The following values are supported

  • MEDIAPROVIDER - Media provider
  • UNKNOWN - Unknown device type

1.5. DeviceDomain

Specifies the network domain in which the device is located.

  enum DeviceDomain { "LOCAL_NETWORK",
                      "UNKNOWN" };

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

The following values are supported

  • LOCAL_NETWORK - Located in local network 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(Device device);
      void ondeviceremoved(Device device);
  };

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

Methods

ondeviceadded
Invoked when a new device has appeared in the network.

  void ondeviceadded(Device device);

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

Parameters:

  • device: A newly discovered device.
ondeviceremoved
Invoked when a device is going to disappear from the network

  void ondeviceremoved(Device device); 

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

Parameters:

  • device: 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;
  };

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

Attributes

  • readonly long depth
    Color depth of the icon in bits per pixel.

    Since : 1.0

    Privilege level: public

    Privilege: http://developer.samsung.com/privilege/allshare

  • readonly long height
    Height of the icon

    Since : 1.0

    Privilege level: public

    Privilege: http://developer.samsung.com/privilege/allshare

  • readonly long width
    Width of the icon

    Since : 1.0

    Privilege level: public

    Privilege: http://developer.samsung.com/privilege/allshare

  • readonly DOMString mimeType
    MIME type of the icon

    Since : 1.0

    Privilege level: public

    Privilege: http://developer.samsung.com/privilege/allshare

  • readonly DOMString iconUri
    Uri of the icon

    Since : 1.0

    Privilege level: public

    Privilege: http://developer.samsung.com/privilege/allshare

2.3. DeviceFinder

Provides methods for finding AllShare devices.

  [NoInterfaceObject] interface DeviceFinder {
      Device? getDevice(DeviceType deviceType,
                        DeviceId id) raises(WebAPIException);
      DeviceArray getDeviceList(DeviceType deviceType) raises(WebAPIException);
      void refresh() raises(WebAPIException);
      long addDeviceDiscoveryListener(DeviceDiscoveryCallback deviceDiscoveryCallback) raises(WebAPIException);
      void removeDeviceDiscoveryListener(long deviceDiscoveryListener) raises(WebAPIException);
  };

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

Methods

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

  Device? getDevice(DeviceType deviceType,
                    DeviceId id) raises(WebAPIException);

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

Parameters:

  • deviceType: Specifies type of device
  • id: Specifies device id

Return value:

Device Specified device object

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

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

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type UnknownError in any other error case.

Code example:


  var serviceProvider; // it is assumed that you obtained serviceProvider. For further details, see the createServiceProvider(..).
  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.

  DeviceArray getDeviceList(DeviceType deviceType) raises(WebAPIException);

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

Parameters:

  • deviceType: Specifies device's type

Return value:

DeviceArray Specified devices array

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

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

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type UnknownError in any other error case.

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.getDeviceList("MEDIAPROVIDER");        

      // Print out how many MediaProvider devices are available
      console.log(devices.length);             
  } catch(e) {
      console.log(e.name);
  }
refresh
Refreshes the list of devices on the network.

  void refresh() raises(WebAPIException);

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

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

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type UnknownError in any other error case.

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.getDeviceList("MEDIAPROVIDER");
      if (providers.length == 0) {
          // Refreshes the device list and retrieves the provider list again.  
          deviceFinder.refresh();
          providers = deviceFinder.getDeviceList("MEDIAPROVIDER");
      }
  } catch(e) {
      console.log(e.name);
  }
addDeviceDiscoveryListener
Registers device discovery event listener.

  long addDeviceDiscoveryListener(DeviceDiscoveryCallback deviceDiscoveryCallback) raises(WebAPIException);

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

Parameters:

  • deviceDiscoveryCallback: Callback function called if the event occurred.

Return value:

long Event listener id

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

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

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type UnknownError in any other error case.

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

  void removeDeviceDiscoveryListener(long deviceDiscoveryListener) raises(WebAPIException);

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

Parameters:

  • deviceDiscoveryListener: Event listener id

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

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

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type UnknownError in any other error case.

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;
  };

Since : 1.0

Privilege level: public

Privilege: http://developer.samsung.com/privilege/allshare

Attributes

  • readonly DeviceId id
    Specifies the unique ID of the device.

    Since : 1.0

    Privilege level: public

    Privilege: http://developer.samsung.com/privilege/allshare

  • readonly DeviceDomain deviceDomain
    Specifies the device domain

    Since : 1.0

    Privilege level: public

    Privilege: http://developer.samsung.com/privilege/allshare

  • readonly DeviceType deviceType
    Specifies the device type

    Since : 1.0

    Privilege level: public

    Privilege: http://developer.samsung.com/privilege/allshare

  • readonly IconArray iconArray
    Specifies icons associated with the device

    Since : 1.0

    Privilege level: public

    Privilege: http://developer.samsung.com/privilege/allshare

  • readonly DOMString ipAddress
    Specifies the device IPv4 adress

    Since : 1.0

    Privilege level: public

    Privilege: http://developer.samsung.com/privilege/allshare

  • readonly optional DOMString modelName
    Specifies the device model name.

    Since : 1.0

    Privilege level: public

    Privilege: http://developer.samsung.com/privilege/allshare

  • readonly DOMString name
    Specifies the device name

    Since : 1.0

    Privilege level: public

    Privilege: http://developer.samsung.com/privilege/allshare

  • readonly DOMString nic
    Specified NIC (Network Interface Controller) name of the device

    Since : 1.0

    Privilege level: public

    Privilege: http://developer.samsung.com/privilege/allshare

3. Full WebIDL


  module DeviceDiscovery {   
      typedef DOMString DeviceId;
      typedef sequence<Device> DeviceArray;
      typedef sequence<Icon> IconArray;

      enum DeviceType { "MEDIAPROVIDER",
                        "UNKNOWN" };

      enum DeviceDomain { "LOCAL_NETWORK",
                          "UNKNOWN" };

      [Callback, NoInterfaceObject] interface DeviceDiscoveryCallback {
          void ondeviceadded(Device device);
          void ondeviceremoved(Device 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 {
          Device? getDevice(DeviceType deviceType,
                            DeviceId id) raises(WebAPIException);
          DeviceArray getDeviceList(DeviceType deviceType) raises(WebAPIException);
          void refresh() raises(WebAPIException);
          long addDeviceDiscoveryListener(DeviceDiscoveryCallback deviceDiscoveryCallback) raises(WebAPIException);
          void removeDeviceDiscoveryListener(long deviceDiscoveryListener) raises(WebAPIException);
      };

      [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;
      };
  };