RemoteAppControl API (Samsung Extension)

The Remote App Control API provides interfaces and methods providing web applications to send a request to the remote device.

This API provides an interface and methods through features such as:

Since: 2.3.2

Table of Contents


Summary of Interfaces and Methods

Interface Method
RemoteAppControlObject
RemoteAppControlManager void launchRemoteAppControl (RemoteApplicationControl appControl, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback, optional RemoteAppControlReplyCallback replyCallback)
RemoteApplicationControl
RemoteAppControlReplyCallback void onsuccess (optional DOMString? data)
void onfailure ()

1. Type Definitions

1.1. ApplicationName

The Application Name of the remote device to explicitly launch.
  typedef DOMString ApplicationName;

Since: 2.3.2

1.2. PackageName

The Package Name of the remote device to explicitly launch.
  typedef DOMString PackageName;

Since: 2.3.2

2. Interfaces

2.1. RemoteAppControlObject

The RemoteAppControlObject interface defines what is instantiated by the WebAPIs object from the Tizen Platform.
  [NoInterfaceObject] interface RemoteAppControlObject {
    readonly attribute RemoteAppControlManager remoteappcontrol;
  };
    WebAPIs implements RemoteAppControlObject;

Since: 2.3.2

There will be a webapis.remoteappcontrol object that allows accessing the functionality of the Remote App Control API.

2.2. RemoteAppControlManager

The RemoteAppControlManager interface is the top-level interface for the Remote App Control API that provides access to the module functionalities.
  [NoInterfaceObject] interface RemoteAppControlManager {

     void launchRemoteAppControl(RemoteApplicationControl appControl,
              optional SuccessCallback? successCallback,
              optional ErrorCallback? errorCallback,
              optional RemoteAppControlReplyCallback replyCallback) raises (WebAPIException);

  };

Methods

launchRemoteAppControl
Send the launch request to the remote device.
void launchRemoteAppControl(RemoteApplicationControl appControl, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback, optional RemoteAppControlReplyCallback replyCallback);
             

Since: 2.3.2

The ErrorCallback method is launched with these error types:

  • TimeoutError - If the request is timeout
  • NotFoundError - If the requested application is not found in the remote device
  • UnknownError - If any other error occurs

Privilege level: public

Privilege: http://tizen.org/privilege/application.launch

Privilege: http://developer.samsung.com/tizen/privilege/accessoryprotocol

Parameters:

  • appControl: The data structure describing remote application control details
  • successCallback [optional] [nullable]: The method to call when the invocation ends successfully
  • errorCallback [optional] [nullable]: Callback function that is called when an error has occurred
  • replyCallback [optional]: Callback function that is called when the application gets back results from the launched remote application

Exceptions:

  • WebAPIException
    • with error type AlreadyRequestedError, if max limit for request queue reached. Can handle new send requests after processing existing requests.

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

    • with error type NotConnectedError, iIf the remote device is not connected.

    • with error type QuotaExceededError, if the size of data has exceeded the maximum limit.

    • 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 NotSupportedError, if feature is not supported.

    • with error type UnknownError in any other error case.

Code example:

 // The following code example launches a specific application explicitly with the package name and application name.
 var remoteAppControlReplyCallback = {
     // callee sent a reply
     onsuccess: function(data) {
         console.log('Received data is ' + data);
     },
     // callee returned failure
     onfailure: function() {
         console.log('The launch remote application control failed');
     }
 }

 var appControl =
       new webapis.RemoteApplicationControl(
                  "http://samsung.com/appcontrol/operation/remote/default",
                  null,
                  "com.sample.testapp",
                  "com.sample.testapp.testActivity",
                  "Test Message");

 webapis.remoteappcontrol.launchRemoteAppControl(
     appControl,
     function() {console.log("launch remote application control succeed");},
     function(e) {console.log("launch remote application control failed. reason: " + e.name);},
     remoteAppControlReplyCallback);

 

Code example:

 // The following code example launches a browesr application with the operation and URI.
 var remoteAppControlReplyCallback = {
     // callee sent a reply
     onsuccess: function(data) {
         console.log('Recevied data is ' + data);
     },
     // callee returned failure
     onfailure: function() {
         console.log('The launch remote application control failed');
     }
 }

 var appControl =
       new webapis.RemoteApplicationControl(
                  "http://samsung.com/appcontrol/operation/remote/view",
                  "http://tizen.org");

 webapis.remoteappcontrol.launchRemoteAppControl(
     appControl,
     function() {console.log("launch remote application control succeed");},
     function(e) {console.log("launch remote application control failed. reason: " + e.name);});

 

2.3. RemoteApplicationControl

This interface consists of an operation, URI, and data. It describes an action to be performed by remote applications and is passed to launch remote applications. If the system gets the application control request, it finds the corresponding application to be launched with the delivered application control and launches the selected application.
  [Constructor(DOMString operation, optional DOMString? uri,
               optional PackageName? packageName, optional ApplicationName? appName,
               optional DOMString? data)]
  interface RemoteApplicationControl {

    attribute DOMString operation;

    attribute DOMString? uri;

    attribute PackageName? packageName;

    attribute ApplicationName? appName;

    attribute DOMString? data;

  };

Since: 2.3.2

Code example:

 var appControl =
       new webapis.RemoteApplicationControl(
                  "http://samsung.com/appcontrol/operation/remote/view",
                  "http://tizen.org");
 

Code example:

 var appControl =
       new webapis.RemoteApplicationControl(
                  "http://samsung.com/appcontrol/operation/remote/default",
                  null,
                  "com.sample.testapp",
                  "com.sample.testapp.testActivity",
                  "Test Message");
 

Constructors

RemoteApplicationControl(DOMString operation, optional DOMString? uri, optional PackageName? packageName, optional ApplicationName? appName, optional DOMString? data);

Attributes

  • DOMString operation
    An attribute to store the string that defines the action to be performed by a remote application control.

    Since: 2.3.2

  • DOMString uri [nullable]
    An attribute to store the URI needed by a remote application control.

    Since: 2.3.2

  • PackageName packageName [nullable]
    An attribute to store the package name of the remote device to explicitly launch.

    Since: 2.3.2

  • ApplicationName appName [nullable]
    An attribute to store the application name of the remote device to explicitly launch.

    Since: 2.3.2

  • DOMString data [nullable]
    An attributes to store the data needed for an application control. The recommended data size is under 32KB.

    Since: 2.3.2

2.4. RemoteAppControlReplyCallback

The RemoteAppControlReplyCallback interface defines the success callback for launchRemoteAppControl().
  [Callback=FunctionOnly, NoInterfaceObject] interface RemoteAppControlReplyCallback {
    void onsuccess(optional DOMString? data);

    void onfailure();
  };

Since: 2.3.2

Methods

onsuccess
Called when the requested operation succeeded by the calle application.
void onsuccess(optional DOMString? data);
             

Since: 2.3.2

Parameters:

  • data [optional] [nullable]: Received data string by the calle application
onfailure
Called when the requested operation failed by the callee application.
void onfailure();
             

Since: 2.3.2

3. Related Feature

It is recommended to design feature related code in a modular way.

To guarantee the running of this application on a device with Remote App Control feature, define the following requirements in the config file:

  • http://developer.samsung.com/tizen/feature/network.accessory_protocol
  • 4. Full WebIDL

    module RemoteAppControl {
    
      [NoInterfaceObject] interface RemoteAppControlObject {
        readonly attribute RemoteAppControlManager remoteappcontrol;
      };
        WebAPIs implements RemoteAppControlObject;
    
      typedef DOMString ApplicationName;
    
      typedef DOMString PackageName;
    
      [NoInterfaceObject] interface RemoteAppControlManager {
    
         void launchRemoteAppControl(RemoteApplicationControl appControl,
                  optional SuccessCallback? successCallback,
                  optional ErrorCallback? errorCallback,
                  optional RemoteAppControlReplyCallback replyCallback) raises (WebAPIException);
    
      };
    
      [Constructor(DOMString operation, optional DOMString? uri,
                   optional PackageName? packageName, optional ApplicationName? appName,
                   optional DOMString? data)]
      interface RemoteApplicationControl {
    
        attribute DOMString operation;
    
        attribute DOMString? uri;
    
        attribute PackageName? packageName;
    
        attribute ApplicationName? appName;
    
        attribute DOMString? data;
    
      };
    
      [Callback=FunctionOnly, NoInterfaceObject] interface RemoteAppControlReplyCallback {
        void onsuccess(optional DOMString? data);
    
        void onfailure();
      };
    
    };