Samsung Electronics logo

Samsung Web API: ASFService

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

Introduction

This API allows developers to initiate the AllShare Framework (ASF) which provides convergence services such as media sharing and control sharing.

The ASF is a component which SAMSUNG devices contain to support it as a service.

For more information on the AllShare features, see AllShare Guide.

Table of Contents

Summary of Interfaces and Methods

Interface Method
WebAPIsAllShareObject
AllShare
ServiceConnectorObject
ServiceProviderCreateSuccessCallback void onsuccess(ServiceProvider serviceProvider)
ServiceProviderErrorCallback void onerror(WebAPIError error, ServiceState state)
ServiceConnector void createServiceProvider(ServiceProviderCreateSuccessCallback successCallback, ServiceProviderErrorCallback errorCallback)
void deleteServiceProvider(SuccessCallback successCallback, ServiceProviderErrorCallback errorCallback)
ServiceProvider? getServiceProvider()
ServiceProvider DeviceFinder getDeviceFinder()
ServiceState getServiceState()

1. Type Definitions

1.1. ServiceState

Specifies the state of ASF service. 

    enum ServiceState {
        "DISABLED", 
        "ENABLED", 
        "UNKNOWN"
    };
  • DISABLED: The service state is "disabled"
  • ENABLED: The service state is "enabled"
  • UNKNOWN: The service state is unknown

2. Interfaces

2.1. WebAPIsAllShareObject

Defines what is instantiated in the AllShareObject. 

    [NoInterfaceObject] interface WebAPIsAllShareObject {

        readonly attribute AllShare allshare;
    
    };
    WebAPIs implements WebAPIsAllShareObject;

ATTRIBUTES

readonly AllShare allshare

The object will provide interfaces for connecting services and obtaining AllShare devices.

This attribute is read-only.

2.2. AllShare

The AllShare root API. 

    [NoInterfaceObject] interface AllShare {

    };

AllShare interfaces are always available within WebAPIs object in the ECMAScript hierarchy (window.webapis.allshare).

2.3. ServiceConnectorObject

Defines what is instantiated in the webapis object. 

    [NoInterfaceObject] interface ServiceConnectorObject {
        
        readonly attribute ServiceConnector serviceconnector;    
    };
    AllShare implements ServiceConnectorObject;

A webapis.allshare.serviceconnector object provides access to the ASF service.

ATTRIBUTES

readonly ServiceConnector serviceconnector

The object provides interfaces for connecting to the ASF service.

This attribute is read-only.

2.4. ServiceProviderCreateSuccessCallback

Provides a callback when a ServiceProvider object is created successfully. 

    [Callback=FunctionOnly, NoInterfaceObject] interface ServiceProviderCreateSuccessCallback {
        
        void onsuccess(ServiceProvider serviceProvider);
        
    };

This callback interface specifies a success callback with ServiceProvider object as an input argument. It is used in an asynchronous operation ServiceConnector.createServiceProvider(...).

METHODS

onsuccess

Invoked when ServiceProvider is created successfully.

Signature
void onsuccess(ServiceProvider serviceProvider);
Parameters
  • serviceProvider
    • Optional: No.
    • Nullable: No.
    • Type: ServiceProvider.
    • Description: the ServiceConnector object which is successfully created

2.5. ServiceProviderErrorCallback

Provides an error callback when the operation of a ServiceProvider object fails. 

    [Callback=FunctionOnly, NoInterfaceObject] interface ServiceProviderErrorCallback {
        
        void onerror(WebAPIError error,
                     ServiceState state);
    };

METHODS

onerror

Invoked when a ServiceProvider operation is failed.

Signature
void onerror(WebAPIError error, ServiceState state);
Parameters
  • error
    • Optional: No.
    • Nullable: No.
    • Type: WebAPIError.
    • Description: WebAPIError object which indicates error type and message.
  • state
    • Optional: No.
    • Nullable: No.
    • Type: ServiceState.
    • Description: Current state of the Service.

2.6. ServiceConnector

Provides the connection to the AllShare Framework(ASF) service. 

    [NoInterfaceObject] interface ServiceConnector {

        void createServiceProvider(ServiceProviderCreateSuccessCallback successCallback, 
                                   optional ServiceProviderErrorCallback errorCallback);
        
        void deleteServiceProvider(SuccessCallback successCallback,
                                   optional ServiceProviderErrorCallback errorCallback);

        ServiceProvider? getServiceProvider();
    };

This interface provides interfaces for creating and deleting an ASF service provider.

METHODS

createServiceProvider

Creates a ServiceProvider object.

Signature
void createServiceProvider(ServiceProviderCreateSuccessCallback successCallback, optional ServiceProviderErrorCallback errorCallback);

Asynchronous function that connects application to AllShare framework, and returns ServiceProvider object in success callback.

If this API is invoked several times, an exception with error type AlreadyConnectedError is thrown synchronously.

The error callback is launched with these error types:

  • NotConnectedServiceError: if the application doesn't connect to allshare framework.
  • InvalidValuesError: If any input parameter contains invalid values.
  • FrameworkNotInstalledError: If framework is not installed.
  • UnknownError: In the case of any other error.

Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: ServiceProviderCreateSuccessCallback.
    • Description: callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: No.
    • Type: ServiceProviderErrorCallback.
    • Description: callback function called if the request if fails
Exceptions
  • WebAPIException:

    with error type UnknownError in any other case.

    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.

    with error type AlreadyConnectedError, if a connection with the allshare service already exists.

Code example
 
 // Define success callback for creating ServiceProvider
 function sProviderCallback(provider) { 
 
         console.log("The service provider has obtained");
 } 
 
 // Define error callback for creating ServiceProvider
 function eProviderCallback(error, state) {
 
         console.log(error.name);
         console.log("Current ASF service state: " + state);
 
 }

 // Try to create ServiceProvider object.
 try {
         webapis.allshare.serviceconnector.createServiceProvider(sProviderCallback, eProviderCallback);
 }
 catch(e) {
         console.log(e.message);
 }

deleteServiceProvider

Deletes ServiceProvider object.

Signature
void deleteServiceProvider(SuccessCallback successCallback, optional ServiceProviderErrorCallback errorCallback);

Asynchronous function, that disconnects application from AllShare framework

The error callback is launched with these error types:

  • NotFoundError: if the serviceProvider does not exist.
  • UnknownError: In the case of any other error.

Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: SuccessCallback.
    • Description: Callback function called if the request is successful
  • errorCallback
    • Optional: Yes.
    • Nullable: No.
    • Type: ServiceProviderErrorCallback.
    • Description: Callback function called if the request is failed
Exceptions
  • WebAPIException:

    with error type UnknownError in anyother case.

    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
 
 // ServiceProvider object - it is assumed that you have created serviceProvider.
 var serviceProvider;
 
 // Define a success callback for deleting ServiceProvider
 function sProviderDeleteCallback() { 
 
         console.log("The ASF service provider has been deleted properly.");
 } 
 
 // Define an error callback for creating ServiceProvider
 function eProviderDeleteCallback(error, state) {
 
         console.log(error.name);
         console.log("The current ASF service state: " + state);
 
 }

 // Try to delete ServiceProvider object.
 try {
         webapis.allshare.serviceconnector.deleteServiceProvider(sProviderDeleteCallback, eProviderDeleteCallback);
 }
 catch(e) {
         console.log(e.message);
 }

getServiceProvider

Returns a ServiceProvider object that is connected to AllShare framework

Signature
ServiceProvider? getServiceProvider();

Synchronous function, that returns the ServiceProvider object created in the application. If the object is deleted, returns null.

Exceptions
  • WebAPIException:

    with error type UnknownError in any other case.

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

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

Code example
 
 try {
         // it is assumed that createServiceProvider() is successfully invoked
         var serviceProvider = webapis.allshare.serviceconnector.getServiceProvider();
        if (serviceProvider == null) {
            console.log("Service provider had not been created properly");
        }
 }
 catch(e) {
         console.log(e.message);
 }

2.7. ServiceProvider

ServiceProvider contains methods allowing you to obtain DeviceFinder object. 

    [NoInterfaceObject] interface ServiceProvider {
        
        DeviceFinder getDeviceFinder(); 
        
        ServiceState getServiceState();         
    };

METHODS

getDeviceFinder

Returns the DeviceFinder object which is used to find allshare devices.

Signature
DeviceFinder getDeviceFinder();
Return value
DeviceFinder object.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other case.

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

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

Code example
 // It is assumed that the ServiceProvider object is successfully obtained. For further details, see the createServiceProvider() or getServiceProvider().
 var serviceProvider; 
  
 try {
      deviceFinder = serviceProvider.getDeviceFinder();
 } catch(e) {
      console.log(e.name);
 }

getServiceState

Provides the current state of the ASF service.

Signature
ServiceState getServiceState();
Return value
ServiceState value.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other case.

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

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

3. Full WebIDL 

module ASFService {

    enum ServiceState {
        "DISABLED", 
        "ENABLED", 
        "UNKNOWN"
    };

    [NoInterfaceObject] interface WebAPIsAllShareObject {

        readonly attribute AllShare allshare;
    
    };
    WebAPIs implements WebAPIsAllShareObject;    
    
    [NoInterfaceObject] interface AllShare {

    };
    
    [NoInterfaceObject] interface ServiceConnectorObject {
        
        readonly attribute ServiceConnector serviceconnector;    
    };
    AllShare implements ServiceConnectorObject;
    
    [Callback=FunctionOnly, NoInterfaceObject] interface ServiceProviderCreateSuccessCallback {
        
        void onsuccess(ServiceProvider serviceProvider);
        
    };    
    
    [Callback=FunctionOnly, NoInterfaceObject] interface ServiceProviderErrorCallback {
        
        void onerror(WebAPIError error,
                     ServiceState state);
    };
    
    [NoInterfaceObject] interface ServiceConnector {

        void createServiceProvider(ServiceProviderCreateSuccessCallback successCallback, 
                                   optional ServiceProviderErrorCallback errorCallback);
        
        void deleteServiceProvider(SuccessCallback successCallback,
                                   optional ServiceProviderErrorCallback errorCallback);

        ServiceProvider? getServiceProvider();
    };
    
    [NoInterfaceObject] interface ServiceProvider {
        
        DeviceFinder getDeviceFinder(); 
        
        ServiceState getServiceState();         
    };
};