SAPService API (Samsung Extension)

The Samsung Accessory Service Framework allows service discovery and the creation of Accessory Service Connections between Application Level Entities (ALE) for data exchange using the Samsung Accessory Protocol(SAP). This functionality is available through the SAP Service API.

The entities in the Samsung Accessory Service are:

Since: 2.2

Table of Contents


Summary of Interfaces and Methods

Interface Method
SAManagerObject
SAManager void requestSAAgent (SAAgentSuccessCallback successCallback, optional ErrorCallback? errorCallback)
void setDeviceStatusListener (SADeviceStatusCallback callback)
SAAgent void requestServiceConnection (SAPeerAgent peerAgent)
void setServiceConnectionListener (ServiceConnectionCallback callback)
void authenticatePeerAgent (SAPeerAgent peerAgent, SAAuthenticatePeerAgentSuccessCallback successCallback, optional ErrorCallback? errorCallback)
void acceptServiceConnectionRequest (SAPeerAgent peerAgent)
void rejectServiceConnectionRequest (SAPeerAgent peerAgent)
void findPeerAgents ()
void setPeerAgentFindListener (SAPeerAgentFindCallback callback)
SAFileTransfer getSAFileTransfer ()
SAMessage getSAMessage ()
SAAuthenticationToken
SAPeerAccessory
SAPeerAgent
SAMessage long sendData (SAPeerAgent peerAgent, DOMString data, SAMessageSendCallback callback)
long sendSecureData (SAPeerAgent peerAgent, DOMString data, SAMessageSendCallback callback)
void setMessageReceiveListener (SAMessageReceiveCallback callback)
SASocket void close ()
boolean isConnected ()
void sendData (SAChannelId channelId, DOMString data)
void sendSecureData (SAChannelId channelId, DOMString data)
void setDataReceiveListener (SADataReceiveCallback callback)
void setSocketStatusListener (SASocketStatusCallback callback)
SAFileTransfer long sendFile (SAPeerAgent peerAgent, DOMString filePath)
void setFileSendListener (SAFileSendCallback callback)
void setFileReceiveListener (SAFileReceiveCallback callback)
void receiveFile (TransferId id, DOMString localPath)
void cancelFile (TransferId id)
void rejectFile (TransferId id)
SADataReceiveCallback void onreceive (SAChannelId channelId, DOMString data)
SASocketStatusCallback void onconnectionlost (SASocketStatusErrorCode reason)
SAFileReceiveCallback void onreceive (TransferId id, DOMString fileName)
void onprogress (TransferId id, unsigned long progress)
void oncomplete (TransferId id, DOMString localPath)
void onerror (SAFileReceiveErrorCode errorCode, TransferId id)
SAFileSendCallback void onprogress (TransferId id, unsigned long progress)
void oncomplete (TransferId id, DOMString localPath)
void onerror (SAFileSendErrorCode errorCode, TransferId id)
SAAgentSuccessCallback void onsuccess (SAAgent[] agents)
SAPeerAgentFindCallback void onpeeragentfound (SAPeerAgent peerAgent)
void onpeeragentupdated (SAPeerAgent peerAgent, PeerAgentStatus status)
void onerror (SAPeerAgentFindErrorCode errorCode)
ServiceConnectionCallback void onrequest (SAPeerAgent peerAgent)
void onconnect (SASocket socket)
void onerror (SAServiceConnectionErrorCode errorCode)
void onerror (SAServiceConnectionErrorCode errorCode, SAPeerAgent peerAgent)
SADeviceStatusCallback void ondevicestatus (TransportType type, DeviceStatus status)
SAAuthenticatePeerAgentSuccessCallback void onsuccess (SAPeerAgent peerAgent, SAAuthenticationToken authToken)
SAMessageSendCallback void onsent (SAPeerAgent peerAgent, long id)
void onerror (SAMessageSendErrorCode errorCode, SAPeerAgent peerAgent, long id)
SAMessageReceiveCallback void onreceive (SAPeerAgent peerAgent, DOMString data)

1. Type Definitions

1.1. SARole

Roles of an SAAgent
    enum SARole {"PROVIDER", "CONSUMER"};

Since: 2.2

The supported roles of an SA are:

  • PROVIDER : A Service Provider.
  • CONSUMER : A Service Consumer consumes the information or service provided by its associated Service Provider.

1.2. TransportType

Transport types
    enum TransportType {"TRANSPORT_BLE", "TRANSPORT_BT", "TRANSPORT_USB", "TRANSPORT_WIFI"};

Since: 2.2

The supported transport types are:

  • TRANSPORT_BLE : Bluetooth Low Energy
  • TRANSPORT_BT : Bluetooth
  • TRANSPORT_USB : USB
  • TRANSPORT_WIFI : WIFI

1.3. DeviceStatus

Device status types of connections with a peer device.
    enum DeviceStatus {"ATTACHED", "DETACHED"};

Since: 2.2

The supported device status types are:

  • ATTACHED : Attached peer device
  • DETACHED : Detached peer device

1.4. PeerAgentStatus

Status types of a peer agent.
    enum PeerAgentStatus {"AVAILABLE", "UNAVAILABLE"};

Since: 2.2

The supported peer agent status types are:

  • AVAILABLE : The peer agent is available on a connected remote device.
  • UNAVAILABLE : The peer agent is unavailable on a connected remote device because the application package containing it is uninstalled from the remote device.

1.5. AuthenticationType

Authentication types
    enum AuthenticationType {"AUTHENTICATION_TYPE_NONE", "AUTHENTICATION_TYPE_CERTIFICATE_X509"};

Since: 2.2

The supported authentication types are:

  • AUTHENTICATION_TYPE_NONE : None
  • AUTHENTICATION_TYPE_CERTIFICATE_X509 : X.509 certificate

1.6. SAPeerAgentFindErrorCode

Error codes for a peer agent search.
    enum SAPeerAgentFindErrorCode {"PEER_NOT_FOUND", "DEVICE_NOT_CONNECTED", "DUPLICATE_REQUEST"};

Since: 2.2

The possible error codes are :

  • PEER_NOT_FOUND : The remote Accessory Peer Agent search failed because there is no matching/desired Accessory Peer Agent on the connected Accessory Device(s).
  • DEVICE_NOT_CONNECTED : The remote Accessory Peer Agent search failed because none of the Accessory Devices are connected.
  • DUPLICATE_REQUEST : The remote Accessory Peer Agent search failed when the findPeerAgent request to duplicate.

1.7. SAServiceConnectionErrorCode

Error codes for a Service Connection.
    enum SAServiceConnectionErrorCode {"ALREADY_EXIST", "NETWORK_ERROR", "DEVICE_UNREACHABLE", "INVALID_PEERAGENT", "PEERAGENT_NO_RESPONSE", "PEERAGENT_REJECTED", "ERROR_REFLECTION_EXCEPTION"};

Since: 2.2

The possible error codes are :

  • ALREADY_EXIST : The remote Accessory Peer Agent already exists.
  • NETWORK_ERROR : The connection failed due to a network error.
  • DEVICE_UNREACHABLE : The remote Accessory Peer Agent is unreachable or no longer available, perhaps it has been powered off or the connectivity has been turned off.
  • INVALID_PEERAGENT : The SAPeerAgent object is invalid.
  • PEERAGENT_NO_RESPONSE : The remote Accessory Peer Agent timedout.
  • PEERAGENT_REJECTED : The remote Accessory Peer Agent rejected the request.
  • ERROR_REFLECTION_EXCEPTION : The framework failed to construct an SASocket object.

1.8. SAFileSendErrorCode

Error codes for sending a file.
    enum SAFileSendErrorCode {"FILE_IO", "PEER_BUSY", "PEER_CHANNEL_IO", "PEER_CONN_LOST", "PEER_NO_RESPONSE", "PEER_REJECTED", "REQUEST_NOT_QUEUED", "SPACE_NOT_AVAILABLE", "UNKNOWN_ERROR"};

Since: 2.2

The possible error codes are :

  • FILE_IO : The file read request failed or the file doesn't exist at the mentioned path.
  • PEER_BUSY : The remote peer is already busy receiving file from another device.
  • PEER_CHANNEL_IO : The remote peer is not reachable.
  • PEER_CONN_LOST : The connection to the remote peer is lost during the file transfer.
  • PEER_NO_RESPONSE : The remote peer did not respond.
  • PEER_REJECTED : The remote peer rejected/cancelled the file request.
  • REQUEST_NOT_QUEUED : The send request is not queued.
  • SPACE_NOT_AVAILABLE : The remote peer does not have enough free space available.
  • UNKNOWN_ERROR : Any other case.

1.9. SAFileReceiveErrorCode

Error codes for receiving a file.
    enum SAFileReceiveErrorCode {"FILE_IO", "PEER_CHANNEL_IO", "PEER_CONN_LOST", "PEER_NO_RESPONSE", "PEER_REJECTED", "SPACE_NOT_AVAILABLE", "UNKNOWN_ERROR"};

Since: 2.2

The possible error codes are :

  • FILE_IO : The file write request failed.
  • PEER_CHANNEL_IO : The remote peer is not reachable.
  • PEER_CONN_LOST : The connection to the remote peer is lost during the file transfer.
  • PEER_NO_RESPONSE : The remote peer did not respond.
  • PEER_REJECTED : The remote peer rejected/cancelled the file request.
  • SPACE_NOT_AVAILABLE : The receiver device does not have enough free space available.
  • UNKNOWN_ERROR : Any other case.

1.10. SASocketStatusErrorCode

Error codes for socket status.
    enum SASocketStatusErrorCode {"PEER_DISCONNECTED", "DEVICE_DETACHED", "UNKNOWN_REASON"};

Since: 2.2

The possible error codes are :

  • PEER_DISCONNECTED : The remote Accessory Peer Agent closed the Service Connection.
  • DEVICE_DETACHED : The remote Accessory Peer Agent Accessory Device has been detached.
  • UNKNOWN_REASON : The remote Accessory Peer Agent has a problem that the Accessory Service Framework cannot identify.

1.11. SAMessageSendErrorCode

Error codes for sending a file.
    enum SAMessageSendErrorCode {"PEER_UNREACHABLE", "PEER_NO_RESPONSE", "UNKNOWN_ERROR"};

Since: 2.3.2

The possible error codes are :

  • PEER_UNREACHABLE : Message delivery failed as the remote Accessory Peer Agent is not reachable or not alive to receive any messages.
  • PEER_NO_RESPONSE : Message delivery failed as the remote Accessory Peer Agent does not give any response within the timeout period
  • UNKNOWN_ERROR : Any other case.

1.12. SAFeatureType

Feature type of the data transfer supported
    enum SAFeatureType {"SOCKET", "MESSAGE"};

Since: 2.3.2

The supported feature type of the data transfer are:

  • SOCKET : Data transfer over socket connection is supported.
  • MESSAGE : Connection less data transfer is supported.

1.13. TransferId

The Transaction ID given by the file transfer utility.
    typedef long TransferId;

Since: 2.2

1.14. SAChannelId

The Channel ID value specified in the Accessory Service Profile.
    typedef long SAChannelId;

Since: 2.2

2. Interfaces

2.1. SAManagerObject

Defines what is instantiated in the webapis object.
    [NoInterfaceObject] interface SAManagerObject {
        readonly attribute SAManager sa;
    };
    WebAPIs implements SAManagerObject;

Since: 2.2

There is a webapis.sa object that allows accessing the functionality of the SAP API.

2.2. SAManager

The SAManager interface gets SAAgents specified in the Accessory Service Profile.
    [NoInterfaceObject] interface SAManager {
        void requestSAAgent(SAAgentSuccessCallback successCallback, optional ErrorCallback? errorCallback);

        void setDeviceStatusListener(SADeviceStatusCallback callback);
    };

Since: 2.2

This interface is always available within the WebAPIs object in the ECMAScript hierarchy (window.webapis.sa).

Methods

requestSAAgent
Requests the SAAgent specified in the Accessory Service Profile.

Deprecated. http://developer.samsung.com/privilege/accessoryprotocol privilege is deprecated since Tizen 2.3. It is recommended to use the http://developer.samsung.com/tizen/privilege/accessoryprotocol privilege (since Tizen 2.3) instead.

void requestSAAgent(SAAgentSuccessCallback successCallback, optional ErrorCallback? errorCallback);
             

Since: 2.2

The ErrorCallback is launched with these error types:

  • ServiceNotAvailableError : If the Accessory Agent registration fails.

Privilege level: public

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

Parameters:

  • successCallback: Callback method to be invoked when SAAgents are successfully returned
  • errorCallback [optional] [nullable]: Callback method to be invoked in case of an error

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:

 function onsuccess(agents){
     for(var i = 0; i < agents.length; i++) {
         if(agents[i].role == "PROVIDER") {
             console.log("Service Provider found! Name : " +  agents[i].name);
         }
         if(agents[i].role == "CONSUMER") {
             console.log("Service Consumer found! Name : " +  agents[i].name);
         }
     }
 }

 function onerror(e) {
     console.log("Error name : " + e.name + ", Error message : " + e.message);
 }

 try {
     webapis.sa.requestSAAgent(onsuccess, onerror);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
setDeviceStatusListener
Sets a listener that is called when a peer device is attached or detached.

Deprecated. http://developer.samsung.com/privilege/accessoryprotocol privilege is deprecated since Tizen 2.3. It is recommended to use the http://developer.samsung.com/tizen/privilege/accessoryprotocol privilege (since Tizen 2.3) instead.

void setDeviceStatusListener(SADeviceStatusCallback callback);
             

Since: 2.2

Privilege level: public

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

Remark : This status handler is useful to notice the host and Gear device disconnected(DETACHED case) or connected(ATTACHED case). Note that in the ATTACHED case, you need to call findePeerAgents() to eventually re-establish a new SASocket connection.

Parameters:

  • callback: Method to be called when a peer device is attached or detached

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:

 function ondevicestatus(type, status){
     if (status == "ATTACHED") {
         console.log("Attached remote peer device. : " + type);
     } else if (status == "DETACHED") {
         console.log("Detached remote peer device. : " + type);
     }
 }

 try {
     webapis.sa.setDeviceStatusListener(ondevicestatus);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 

2.3. SAAgent

The SAAgent interface is the main interface between Service Provider/Service Consumer applications and the Accessory Service Framework.
    [NoInterfaceObject] interface SAAgent {
        readonly attribute DOMString id;

        readonly attribute DOMString name;

        readonly attribute SARole role;

        readonly attribute SAChannelId[] channelIds;

        void requestServiceConnection(SAPeerAgent peerAgent);

        void setServiceConnectionListener(ServiceConnectionCallback callback);

        void authenticatePeerAgent(SAPeerAgent peerAgent, SAAuthenticatePeerAgentSuccessCallback successCallback, optional ErrorCallback? errorCallback);

        void acceptServiceConnectionRequest(SAPeerAgent peerAgent);

        void rejectServiceConnectionRequest(SAPeerAgent peerAgent);

        void findPeerAgents();

        void setPeerAgentFindListener(SAPeerAgentFindCallback callback);

        SAFileTransfer getSAFileTransfer();

        SAMessage getSAMessage();
    };

Since: 2.2

This interface is the the main interface for an application to interact with the Accessory Service Framework. The application should provide Accessory Service Profile information in an XML file, for example /res/<yourname>.xml, and declare the path of the XML file in the config.xml file of the your web application project as follows.

In case of Web Application : <tizen:metadata key="AccessoryServicesLocation" value="res/serviceprofile.xml"/>

In case of Web Widget : <tizen:widget-metadata key="AccessoryServicesLocation" value="widget/res/xml/serviceprofile.xml"/>

An example of an accessory XML file (/res/<yourname>.xml) specifying the Accessory Service Profile details is illustrated below:

A single application may include multiple Service Providers and/or Service Consumers. To do that, declare multiple <serviceProfile> elements inside the <application> element.

  • The role attribute must be either "provider" or "consumer".
  • The name is the friendly name of a Service Provider or Service Consumer.
  • The id is the Service Profile identifier of a Service Provider or Service Consumer.
  • The version attribute should specify the Service Profile specification version that a Service Provider or Service Consumer follows/implements.
  • The autoLaunchAppId attribute is optional. It should set the application ID of the application that should be invoked by an incoming Service Connection request. If a peer agent requests for a Service Connection with this service profile while it is not running, the system launches this application. Unless this value is specified, the system never launches this application even if the peer agent requests for a Service Connection. E.g. autoLaunchAppId="VcGvmQlo1i.HelloAccessory".
  • The optional serviceLimit attribute sets a limit for the number of concurrent peer agent connections. If a peer agent requests for a Service Connection when the application has already reached the limit, the Samsung Accessory Framework rejects the connection request. The attribute can take one of the following values:
    - ONE_PEERAGENT can support only one peer agent.
    - ONE_ACCESSORY can support only one Accessory Device, but connection to multiple peer agents on that Accessory Device is supported.
    - ANY can support multiple peer agents (this is the default value).
  • The optional serviceTimeout controls the timeout for handling incoming Service Connection requests. In some cases, the application may not be able to accept or reject an incoming Service Connection request immediately. Some examples might be: a need to connect to an external resource such as a cloud server, or a need to do authentification. The timeout value declares the maximum time the application takes to make a decision(accept or reject) before the requesting peer agent gets a Service Connection failed error with PEERAGENT_NO_RESPONSE as the reason.

The <supportedTransports> element declares the transport(s) on which a Service Provider or Service Consumer is able to operate, as shown in the example code. Currently, the Samsung Accessory Service Framework supports the following transport types:

  • TRANSPORT_WIFI
  • TRANSPORT_BT
  • TRANSPORT_BLE
  • TRANSPORT_USB

If a Service Provider or Service Consumer supports multiple transport types, it should declare multiple <transport> elements.

The <serviceChannel> elements may have the following attributes:

  • dataRate is either "low" or "high".
  • priority is "low", "medium", or "high".
  • reliability is "enable" or "disable". In case of packet drop, reliable transfer re-transmits the packet, but incurs additional overhead as a result.

The <supportedFeatures> element declares the feture type of the data transfer supported. Currently, the Samsung Accessory Service Framework supports the following feature types:

  • message

If you need to use Message exchange protocol service without any service connection, it should declare message feature type inside the <supportedFeatures> element.

Code example:

  <resources>
      <application name = "my application">
      <serviceProfile
          role="provider"
          name="smartview"
          id="/sample/gallery"
          version="1.0"
          serviceLimit="ONE_PEERAGENT"
          serviceTimeout="30">
          <supportedTransports>
              <transport type="TRANSPORT_BT"/>
          </supportedTransports>
          <serviceChannel
              id="100"
              dataRate = "high"
              priority = "low"
              reliability= "enable"/>
      </serviceProfile>
      <serviceProfile
          role="provider"
          name="message_service_provider"
          id="/sample/messages"
          version="1.0"
          autoLaunchAppId="VcGvmQlo1i.HelloAccessory"
          serviceLimit="ANY">
          <supportedTransports>
              <transport type="TRANSPORT_BT"/>
          </supportedTransports>
          <serviceChannel
              id="902"
              dataRate = "low"
              priority = "low"
              reliability= "disable"/>
      </serviceProfile>
      <serviceProfile
          role="consumer"
          name="messagetransfer"
          id="/sample/messagetransfer"
          version="1.0"
          serviceLimit="ANY">
          <supportedTransports>
              <transport type="TRANSPORT_BT"/>
          </supportedTransports>
          <supportedFeatures>
              <feature type="message"/>
          </supportedFeatures>
      </serviceProfile>
      </application>
  </resources>
 

Attributes

  • readonly DOMString id
    The ID read from the Service Profile, which is the Service Profile identifier of a Service Provider or Service Consumer.

    Since: 2.2

  • readonly DOMString name
    The name read from the Service Profile, which is the friendly name of a Service Provider or Service Consumer.

    Since: 2.2

  • readonly SARole role
    The role of the SAAgent read from the Service Profile. The available values are "PROVIDER" and "CONSUMER".

    Since: 2.2

  • readonly SAChannelId[] channelIds
    The channel information read from the Service Profile.

    Since: 2.2

Methods

requestServiceConnection
Requests to establish a Service Connection with a remote Accessory Peer Agent.
void requestServiceConnection(SAPeerAgent peerAgent);
             

Since: 2.2

A Service Provider or Service Consumer application may call this method to establish a Service Connection with a remote Accessory Peer Agent. The application is notified of the result of a Service Connection request via the ServiceConnectionCallback registered by setServiceConnectionListener(), which reports whether the request is accepted and a Service Connection is established, or the request for a Service Connection did not succeed.

The application is expected to ensure the availability of the Accessory Peer Agent before calling this method. This method is typically called in the SAPeerAgentFindSuccessCallback callback.

Parameters:

  • peerAgent: Accessory Peer Agent with which a Service Connection is to be established

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:

 // Assume agent object has been obtained by using requestSAAgent() method.
 var callback = {
     onrequest : function(peerAgent){
         // DO SOMETHING
     },
     onconnect : function(socket){
         // Connected
     },
     onerror : function(errorCode){
         // DO SOMETHING
     }
 };

 function onpeeragentfound(peerAgent) {
     if(peerAgent.appName == "expected app name") {
         try {
             agent.requestServiceConnection(peerAgent);
         } catch(e) {
             console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
         }
     }
 }

 function onpeeragentupdated(peerAgent, status) {
     if(status == "AVAILABLE") {
         try {
             agent.requestServiceConnection(peerAgent);
         } catch(e) {
             console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
         }
     } else if(status == "UNAVAILABLE") {
         console.log("Uninstalled application package of peerAgent on remote device.");
     }
 }

 function onerror(errorCode) {
     console.log("Error code : " + errorCode);
     if(errorCode == "PEER_NOT_FOUND") {
         console.log("If remote application is not already installed on the remote device, Please wait onpeeragentupdated callback.");
     }
 }

 var peeragentfindcallback = {
     onpeeragentfound : onpeeragentfound,
     onpeeragentupdated : onpeeragentupdated,
     onerror : onerror
 };

 try {
     agent.setServiceConnectionListener(callback);
     agent.setPeerAgentFindListener(peeragentfindcallback);
     agent.findPeerAgents();
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
setServiceConnectionListener
Sets a listener to get both a connection request and connection establish event.
void setServiceConnectionListener(ServiceConnectionCallback callback);
             

Since: 2.2

  • The onconnect() method of ServiceConnectionCallback is invoked when a connection between a Service Provider and Service Consumer application is established.
  • The onrequest() method of ServiceConnectionCallback is invoked when a remote Accessory Peer Agent requests for a Service Connection with this application.
  • The onerror() method of ServiceConnectionCallback is invoked when an error occurs during the connect/request operation.

Parameters:

  • callback: Callback function to receive a notification of the connect/request event

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:

 // Assume agent object has been obtained by using requestSAAgent() method.
 var callback = {
     onrequest : function(peerAgent){
         // DO SOMETHING
     },
     onconnect : function(socket){
         // DO SOMETHING
     },
     onerror : function(errorCode){
         // DO SOMETHING
     }
 };

 try {
     agent.setServiceConnectionListener(callback);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
authenticatePeerAgent
Gets authentication info of remote peer application.
void authenticatePeerAgent(SAPeerAgent peerAgent, SAAuthenticatePeerAgentSuccessCallback successCallback, optional ErrorCallback? errorCallback);
             

Since: 2.2

The ErrorCallback is launched with these error types:

  • TokenNotGeneratedError : if the authentication token of remote peer agent is not generated.

Parameters:

  • peerAgent: Remote SAPeerAgent that requests to connect with the SAAgent
  • successCallback: Callback method to be invoked when authentication info of remote peer are successfully returned
  • errorCallback [optional] [nullable]: Callback method to be invoked in case of an error

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:

 // Assume agent object has been obtained by using requestSAAgent() method.
 var callback = {
     onrequest : function(peerAgent){
         try {
             agent.authenticatePeerAgent(peerAgent,
                                     function(peerAgent, authToken) {
                                         if (authToken.key == localPublicKey) {
                                             agent.acceptServiceConnectionRequest(peerAgent);
                                         } else {
                                             agent.rejectServiceConnectionRequest(peerAgent);
                                         }
                                     },
                                     function(e) {
                                         console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
                                     });
         } catch(e) {
             console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
         }
     },
     onconnect : function(socket){
         // DO SOMETHING
     },
     onerror : function(errorCode){
         // DO SOMETHING
     }
 };

 try {
     agent.setServiceConnectionListener(callback);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
acceptServiceConnectionRequest
Accepts an incoming Service Connection request from a remote Accessory Peer Agent.
void acceptServiceConnectionRequest(SAPeerAgent peerAgent);
             

Since: 2.2

Parameters:

  • peerAgent: Remote SAPeerAgent that requests to connect with the SAAgent

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:

 // Assume agent object has been obtained by using requestSAAgent() method.
 var callback = {
     onrequest : function(peerAgent){
         if(peerAgent.appName == "expected_appName") {
             try {
                 agent.acceptServiceConnectionRequest(peerAgent);
             } catch(e) {
                 console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
             }
         } else {
             // DO SOMETHING
         }
     },
     onconnect : function(socket){
         // DO SOMETHING
     },
     onerror : function(errorCode){
         // DO SOMETHING
     }
 };

 try {
     agent.setServiceConnectionListener(callback);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
rejectServiceConnectionRequest
Rejects an incoming Service Connection request from a remote Accessory Peer Agent.
void rejectServiceConnectionRequest(SAPeerAgent peerAgent);
             

Since: 2.2

Parameters:

  • peerAgent: Remote SAPeerAgent that requests to connect with the SAAgent

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:

 // Assume agent object has been obtained by using requestSAAgent() method.
 var callback = {
     onrequest : function(peerAgent){
         if(peerAgent.appName == "expected_appName") {
             // DO SOMETHING
         } else {
             try {
                 agent.rejectServiceConnectionRequest(peerAgent);
             } catch(e) {
                 console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
             }
         }
     },
     onconnect : function(socket){
         // DO SOMETHING
     },
     onerror : function(errorCode){
         // DO SOMETHING
     }
 };

 try {
     agent.setServiceConnectionListener(callback);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
findPeerAgents
Finds a matching Accessory Peer Agent.
void findPeerAgents();
             

Since: 2.2

This method starts finding matching Accessory Peer Agents. If any matching Accessory Peer Agent is found, the application notifies via the onpeeragentfound callback that is registered by the setPeerAgentFindListener function. If multiple matching Accessory Peer Agents are found, the callback is invoked multiple times, once for each matching Accessory Peer Agent.

Exceptions:

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

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

Code example:

 // Assume agent object has been obtained by using requestSAAgent() method.
 function onpeeragentfound(peerAgent) {
     if(peerAgent.appName == "expected app name") {
         //DO SOMETHING
     }
 }

 function onpeeragentupdated(peerAgent, status) {
     if(status == "AVAILABLE") {
         try {
             //DO SOMETHING
         } catch(e) {
             console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
         }
     } else if(status == "UNAVAILABLE") {
         console.log("Uninstalled application package of peerAgent on remote device.");
     }
 }

 function onerror(errorCode) {
     console.log("Error code : " + errorCode);
     if(errorCode == "PEER_NOT_FOUND") {
         console.log("If remote application is not already installed on the remote device, Please wait onpeeragentupdated callback.");
     }
 }

 var peeragentfindcallback = {
     onpeeragentfound : onpeeragentfound,
     onpeeragentupdated : onpeeragentupdated,
     onerror : onerror
 };

 try {
     agent.setPeerAgentFindListener(peeragentfindcallback);
     agent.findPeerAgents();
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
setPeerAgentFindListener
Sets a listener to set the found remote Accessory Peer Agents.
void setPeerAgentFindListener(SAPeerAgentFindCallback callback);
             

Since: 2.2

  • The onpeeragentfound() method of SAPeerAgentFindCallback is invoked when a remote Accessory Peer Agent is found.
  • The onpeeragentupdated() method of SAPeerAgentFindCallback is invoked to notify an application of a change in the status of a peer agent on a remote device.
  • The onerror() method of SAPeerAgentFindCallback is invoked when an error occurs while finding a remote Accessory Peer Agent.

Parameters:

  • callback: Callback function to receive a notification of the remote Accessory Peer Agent found event

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:

 // Assume agent object has been obtained by using requestSAAgent() method.
 function onpeeragentfound(peerAgent) {
     if(peerAgent.appName == "expected app name") {
         //DO SOMETHING
     }
 }

 function onpeeragentupdated(peerAgent, status) {
     if(status == "AVAILABLE") {
         //DO SOMETHING
     }
 }

 function onerror(errorCode) {
     console.log("Error code : " + errorCode);
 }

 var peeragentfindcallback = {
     onpeeragentfound : onpeeragentfound,
     onpeeragentupdated : onpeeragentupdated,
     onerror : onerror
 };

 try {
     agent.setPeerAgentFindListener(peeragentfindcallback);
     agent.findPeerAgents();
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
getSAFileTransfer
Gets an object with which all file transfer functionalities can be accessed.
SAFileTransfer getSAFileTransfer();
             

Since: 2.2

Exceptions:

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

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

Code example:

 // Assume agent object has been obtained by using requestSAAgent() method.
 try {
     var filetransfer = agent.getSAFileTransfer();
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
getSAMessage
Gets an object with which message service functionalities can be accessed.
SAMessage getSAMessage();
             

Since: 2.3.2

Remark : If you need to use SAMessage Object for message exchange without any service connection, the message feature type inside the <supportedFeatures> element should declare in serviceprofile.xml.

Exceptions:

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

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

Code example:

 // Assume agent object has been obtained by using requestSAAgent() method.
 try {
     var message = agent.getSAMessage();
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 

2.4. SAAuthenticationToken

The SAAuthenticationToken interface contains authentication information of remote peer agent.
    [NoInterfaceObject] interface SAAuthenticationToken {
        readonly attribute AuthenticationType authenticationType;

        readonly attribute DOMString key;
    };

Since: 2.2

Attributes

  • readonly AuthenticationType authenticationType
    The type of the Authentication token.

    Since: 2.2

  • readonly DOMString key
    The key corresponding to this authentication token.

    Since: 2.2

2.5. SAPeerAccessory

The SAPeerAccessory interface contains information of the Accessory Device on which an Accessory Peer Agent runs.
    [NoInterfaceObject] interface SAPeerAccessory {
        readonly attribute DOMString deviceAddress;

        readonly attribute DOMString deviceName;

        readonly attribute DOMString productId;

        readonly attribute TransportType transportType;

        readonly attribute DOMString vendorId;

        readonly attribute DOMString accessoryId;
    };

Since: 2.2

Attributes

  • readonly DOMString deviceAddress
    The address of the Accessory Device.

    Since: 2.2

  • readonly DOMString deviceName
    The name of the Accessory Device.

    Since: 2.2

  • readonly DOMString productId
    The product identifier of the Accessory Device.

    Since: 2.2

  • readonly TransportType transportType
    The transport type supported by the Accessory Device.

    Since: 2.2

  • readonly DOMString vendorId
    The vendor identifier of the Accessory Device.

    Since: 2.2

  • readonly DOMString accessoryId
    The unique accessory identifier of the Accessory Device.

    Since: 2.2.1.3

2.6. SAPeerAgent

The SAPeerAgent interface contains information of an Accessory Peer Agent and the Accessory Device on which the Accessory Peer Agent runs.
    [NoInterfaceObject] interface SAPeerAgent {
        readonly attribute SAPeerAccessory peerAccessory;

        readonly attribute DOMString appName;

        readonly attribute long maxAllowedDataSize;

        readonly attribute DOMString peerId;

        readonly attribute DOMString profileVersion;

        readonly attribute SAFeatureType[] feature;
    };

Since: 2.2

Attributes

  • readonly SAPeerAccessory peerAccessory
    The Accessory Device on which the Accessory Peer Agent runs.

    Since: 2.2

  • readonly DOMString appName
    The name of the application to which the Accessory Peer Agent belongs.

    Since: 2.2

  • readonly long maxAllowedDataSize
    The maximum payload size supported for sendData() and secureSendData().

    Since: 2.2

  • readonly DOMString peerId
    The identifier of the Accessory Peer Agent.

    Since: 2.2

  • readonly DOMString profileVersion
    The Service Profile specification version that the Accessory Peer Agent supports.

    Since: 2.2

  • readonly SAFeatureType[] feature
    The Feature type of the data transfer supported.

    Since: 2.3.2

2.7. SAMessage

Represents an instance for a MessageService between a Service Provider and Service Consumer.
    [NoInterfaceObject] interface SAMessage {
        long sendData(SAPeerAgent peerAgent, DOMString data, SAMessageSendCallback callback);

        long sendSecureData(SAPeerAgent peerAgent, DOMString data, SAMessageSendCallback callback);

        void setMessageReceiveListener(SAMessageReceiveCallback callback);
    };

Since: 2.3.2

Methods

sendData
Sends string data to a remote Accessory Peer Agent.
long sendData(SAPeerAgent peerAgent, DOMString data, SAMessageSendCallback callback);
             

Since: 2.3.2

Sends a message to an remote Accessory Peer Agent. To find matching Accessory Peer Agent, please use SAAgent.findPeerAgents(). The string must not be longer than the value of the maxAllowedDataSize attribute in the SAPeerAgent interface.

Parameters:

  • peerAgent: Remote Accessory Peer Agent to whom the message is delivered
  • data: Data string to be written
  • callback: Callback method to be invoked when sending a message

Return value:

long ID sending a message

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if the length of the string is longer than the value of the maxAllowedDataSize attribute or the peerAgent is invalid.

    • with error type IOError, if an I/O-related error occurs while sending data.

    • 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:

 // Assume agent object has been obtained by using requestSAAgent() method.
 var messageId = null;
 var saMessage = null;

 var peeragentfindcallback = {
     onpeeragentfound : function(peerAgent) {
         if(peerAgent.feature.filter(function(t){return t === "MESSAGE";}) == "MESSAGE") {
             try {
                 messageId = saMessage.sendData(peerAgent, "Test Message", {
                                         onsent : function(peerAgent, id) {
                                             console.log(id + " message is successfully sent");
                                         },
                                         onerror : function(code, peerAgent, id) {
                                             // DO SOMETHING
                                         }});
             } catch(e) {
                 console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
             }
         }
     },
     onerror : function(errorCode){
         // DO SOMETHING
     }
 };

 try {
     saMessage = agent.getSAMessage();
     agent.setPeerAgentFindListener(peeragentfindcallback);
     agent.findPeerAgents();
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
sendSecureData
Sends encrypted sting data to a remote Accessory Peer Agent.
long sendSecureData(SAPeerAgent peerAgent, DOMString data, SAMessageSendCallback callback);
             

Since: 2.3.2

Sends an encrypted message to an remote Accessory Peer Agent. To find matching Accessory Peer Agent, please use SAAgent.findPeerAgents(). The string must not be longer than the value of the maxAllowedDataSize attribute in the SAPeerAgent interface.

Parameters:

  • peerAgent: Remote Accessory Peer Agent to whom the message is delivered
  • data: Data string to be written
  • callback: Callback method to be invoked when sending a message

Return value:

long ID sending a message

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if the length of the string is longer than the value of the maxAllowedDataSize attribute or the channel is invalid.

    • with error type IOError, if an I/O-related error occurs while sending data.

    • 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:

 // Assume agent object has been obtained by using requestSAAgent() method.
 var messageId = null;
 var saMessage = null;

 var peeragentfindcallback = {
     onpeeragentfound : function(peerAgent) {
         if(peerAgent.feature.filter(function(t){return t === "MESSAGE";}) == "MESSAGE") {
             try {
                 messageId = saMessage.sendSecureData(peerAgent, "Test Secure Message", {
                                         onsent : function(peerAgent, id) {
                                             console.log(id + " message is successfully sent");
                                         },
                                         onerror : function(code, peerAgent, id) {
                                             // DO SOMETHING
                                         }});
             } catch(e) {
                 console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
             }
         }
     },
     onerror : function(errorCode){
         // DO SOMETHING
     }
 };

 try {
     saMessage = agent.getSAMessage();
     agent.setPeerAgentFindListener(peeragentfindcallback);
     agent.findPeerAgents();
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
setMessageReceiveListener
Sets a listener that is called when message is received from a remote Accessory Peer Agent.
void setMessageReceiveListener(SAMessageReceiveCallback callback);
             

Since: 2.3.2

Parameters:

  • callback: Called when message is received from a remote Accessory Peer Agent

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:

 // Assume saMessage object has been obtained by using getSAMessage() method.
 function onreceive(peerAgent, data){
     console.log("Message received from the " + peerAgent.peerId + " : " + data);
 }

 try {
     saMessage.setMessageReceiveListener(onreceive);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 

2.8. SASocket

Represents an instance of a Service Connection between a Service Provider and Service Consumer.
    [NoInterfaceObject] interface SASocket {
        readonly attribute SAPeerAgent peerAgent;

        void close();

        boolean isConnected();

        void sendData(SAChannelId channelId, DOMString data);

        void sendSecureData(SAChannelId channelId, DOMString data);

        void setDataReceiveListener(SADataReceiveCallback callback);

        void setSocketStatusListener(SASocketStatusCallback callback);
    };

Since: 2.2

Attributes

  • readonly SAPeerAgent peerAgent
    The object containing information about a connected remote Accessory Peer Agent, and information about the Accessory Device on which the Accessory Peer Agent runs.

    Since: 2.2

Methods

close
Closes the Service Connection established with a remote Accessory Peer Agent.
void close();
             

Since: 2.2

Exceptions:

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

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

Code example:

 // Assume agent object has been obtained by using requestSAAgent() method.
 var callback = {
     onrequest : function(peerAgent){
         // DO SOMETHING
     },
     onconnect : function(socket){
         if(socket.peerAgent.appName != "expected_appName") {
             try {
                 socket.close();
             } catch(e) {
                 console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
             }
         }
     },
     onerror : function(errorCode){
         // DO SOMETHING
     }
 };

 try {
     agent.setServiceConnectionListener(callback);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
isConnected
Returns the status of an underlying Accessory Service Connection.
boolean isConnected();
             

Since: 2.2

Return value:

boolean true if an active Service Connection to the remote SAPeerAgent exists
false if the Service Connection has been terminated.

Exceptions:

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

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

Code example:

 // Assume agent object has been obtained by using requestSAAgent() method.
 var callback = {
     onrequest : function(peerAgent){
         // DO SOMETHING
     },
     onconnect : function(socket){
         if(socket.peerAgent.appName != "expected_appName") {
             try {
                 var result = socket.isConnected();
             } catch(e) {
                 console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
             }
         }
     },
     onerror : function(errorCode){
         // DO SOMETHING
     }
 };

 try {
     agent.setServiceConnectionListener(callback);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
sendData
Sends string data to a remote Accessory Peer Agent.
void sendData(SAChannelId channelId, DOMString data);
             

Since: 2.2

Sends a string to the specified Service Channel. The string must not be longer than the value of the maxAllowedDataSize attribute in the SAPeerAgent interface.

Parameters:

  • channelId: Channel identifier for the channel to write data, it is specified in the Accessory Application Protocol specification and should be declared in the XML file
  • data: Data string to be written

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if the length of the string is longer than the value of the maxAllowedDataSize attribute or the channel is invalid.

    • with error type IOError, if an I/O-related error occurs while sending data.

    • 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:

 // Assume agent object has been obtained by using requestSAAgent() method.
 var callback = {
     onrequest : function(peerAgent){
         // DO SOMETHING
     },
     onconnect : function(socket){
         for(var i = 0; i < agent.channelIds.length; i++) {
             try {
                 socket.sendData(agent.channelIds[i], "Test String to "+i+"th channel.");
             } catch(e) {
                 console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
             }
         }
     },
     onerror : function(errorCode){
         // DO SOMETHING
     }
 };

 try {
     agent.setServiceConnectionListener(callback);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
sendSecureData
Sends encrypted sting data to a remote Accessory Peer Agent.
void sendSecureData(SAChannelId channelId, DOMString data);
             

Since: 2.2

Sends an encrypted string to the specified Service Channel. The string must not be longer than value of the maxAllowedDataSize attribute in the SAPeerAgent interface.

Parameters:

  • channelId: Channel identifier for the channel to write data, it is specified in the Accessory Application Protocol specification and should be declared in the XML file
  • data: Data string to be written

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if the length of the string is longer than the value of the maxAllowedDataSize attribute or the channel is invalid.

    • with error type IOError, if an I/O-related error occurs while sending data.

    • 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:

 // Assume agent object has been obtained by using requestSAAgent() method.
 var callback = {
     onrequest : function(peerAgent){
         // DO SOMETHING
     },
     onconnect : function(socket){
         for(var i = 0; i < agent.channelIds.length; i++) {
             try {
                 socket.sendSecureData(agent.channelIds[i], "Test String to "+i+"th channel.");
             } catch(e) {
                 console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
             }
         }
     },
     onerror : function(errorCode){
         // DO SOMETHING
     }
 };

 try {
     agent.setServiceConnectionListener(callback);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
setDataReceiveListener
Sets a listener that is called when data is received from a remote Accessory Peer Agent.
void setDataReceiveListener(SADataReceiveCallback callback);
             

Since: 2.2

Parameters:

  • callback: Called when data is received from a remote Accessory Peer Agent

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:

 // Assume socket object has been obtained by using setServiceConnectionListener() method.
 function onreceive(channelId, data){
     console.log("Message received from the channel " + channelId + " : " + data);
 }

 try {
     socket.setDataReceiveListener(onreceive);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
setSocketStatusListener
Sets a listener to monitor the socket's connection status.
void setSocketStatusListener(SASocketStatusCallback callback);
             

Since: 2.2

The connection may be lost for various reasons. For example:

  • The Accessory Device went out of the range of the wireless connectivity.
  • The Accessory Peer Agent terminated the Service Connection.
  • An error occurred which resulted in the Service Connection being terminated.

The reason for the Service Connection being lost is indicated via the errorCode.

The application is expected to implement appropriate error handling mechanisms in this callback method. For example, the application should stop sending data on channels of the Service Connection if the connection is lost.

Parameters:

  • callback: Callback function to be invoked when a Service Connection is lost

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:

 // Assume socket object has been obtained by using setServiceConnectionListener() method.
 function onconnectionlost (reason){
     console.log("Service Connection disconnected due to following reason : "+ reason);
 }

 try {
     socket.setSocketStatusListener(onconnectionlost);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 

2.9. SAFileTransfer

Represents an instance of a File Transfer between a Service Provider and Service Consumer.
    [NoInterfaceObject] interface SAFileTransfer {

        readonly attribute DOMString defaultReceivePath;

        long sendFile(SAPeerAgent peerAgent, DOMString filePath);

        void setFileSendListener(SAFileSendCallback callback);

        void setFileReceiveListener(SAFileReceiveCallback callback);

        void receiveFile(TransferId id, DOMString localPath);

        void cancelFile(TransferId id);

        void rejectFile(TransferId id);
    };

Since: 2.2

Attributes

  • readonly DOMString defaultReceivePath
    The default path where the received file is stored.

    Since: 2.2

Methods

sendFile
Sends a file to a connected peer.
long sendFile(SAPeerAgent peerAgent, DOMString filePath);
             

Since: 2.2

The filePath is either a path from the virtual root or the URI path as described in the Filesystem API.

Parameters:

  • peerAgent: RemotePeer agent who receives the file
  • filePath: Path of the file to send

Return value:

long Transaction ID of the file transfer request

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if the URI scheme name of the file path is invalid or the virtual root is invalid.

    • 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:

 // Assume agent object has been obtained by using requestSAAgent() method.
 var filePath = "file:///opt/usr/media/Downloads/Image.jpg";
 var transferId = null;
 var filetransfer = null;

 var peeragentfindcallback = {
     onpeeragentfound : function(peerAgent) {
         if(peerAgent.appName == "expected app name") {
             try {
                 transferId = filetransfer.sendFile(peerAgent, filePath);
             } catch(e) {
                 console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
             }
         }
     },
     onerror : function(errorCode){
         // DO SOMETHING
     }
 };

 try {
     filetransfer = agent.getSAFileTransfer();
     agent.setPeerAgentFindListener(peeragentfindcallback);
     agent.findPeerAgents();
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
setFileSendListener
Sets a listener to obtain a file's send status, such as on file progress, on send complete, and on any error status.
void setFileSendListener(SAFileSendCallback callback);
             

Since: 2.2

Parameters:

  • callback: Callback function to be invoked when sending a file

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:

 // Assume filetransfer object has been obtained by using getSAFileTransfer() method.
 var callback = {
     onprogress : function(transferId, progress){
         console.log("onprogress transferId : " + transferId + ", progress : " + progress);
     },
     oncomplete : function(transferId, localPath){
         console.log("File transfer complete.  transferId : " + transferId);
     },
     onerror : function(errorCode, transferId){
         console.log("FileSendError transferId : " + transferId + " code : " + errorCode);
     }
 };

 try {
     filetransfer.setFileSendListener(callback);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
setFileReceiveListener
Sets a listener to obtain a file's receive status, such as on receive file, on file progress, on receive complete, and on any error situation.
void setFileReceiveListener(SAFileReceiveCallback callback);
             

Since: 2.2

Parameters:

  • callback: Callback function to be invoked when receiving a file

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:

 // Assume filetransfer object has been obtained by using getSAFileTransfer() method.
 var callback = {
     onreceive : function(transferId, fileName){
         console.log("Incoming file transfer request form the remote peer agent. transferId : " + transferId + " file name : " + fileName);
     },
     onprogress : function(transferId, progress){
         console.log("onprogress transferId : " + transferId + ", progress : " + progress);
     },
     oncomplete : function(transferId, localPath){
         console.log("File transfer complete.  transferId : " + transferId);
     },
     onerror : function(errorCode, transferId){
         console.log("FileReceiveError  transferId : " + transferId + " code : " + errorCode);
     }
 };

 try {
     filetransfer.setFileReceiveListener(callback);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
receiveFile
Called by the receiver of the file.
void receiveFile(TransferId id, DOMString localPath);
             

Since: 2.2

Parameters:

  • id: Transaction ID given by the file transfer utility
  • localPath: Path where the file is stored
    It should include the file name.
    If the value is an empty string, the file is stored in the default path(refer the defaultReceivePath attribute).
    If the file already exists, it is renamed as the file name with the timestamp added to it.

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if the URI scheme name of the file path is invalid or the virtual root is invalid, or the transaction ID is invalid.

    • 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:

 // Assume filetransfer object has been obtained by using getSAFileTransfer() method.
 var newFilePath = "file:///opt/usr/media/Downloads/ReceivedImage.jpg";

 var callback = {
     onreceive : function(transferId, fileName){
         try {
             filetransfer.receiveFile(transferId, newFilePath);
         } catch(e) {
             console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
         }
     },
     onprogress : function(transferId, progress){
         console.log("onprogress transferId : " + transferId + ", progress : " + progress);
     },
     oncomplete : function(transferId, localPath){
         console.log("File transfer complete.  transferId : " + transferId);
     },
     onerror : function(errorCode, transferId){
         console.log("FileReceiveError  transferId : " + transferId + " code : " + errorCode);
     }
 };

 try {
     filetransfer.setFileReceiveListener(callback);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
cancelFile
Cancels an ongoing file transfer. This may be called by the sender or receiver of the file.
This API is available for both the sender and receiver side.
void cancelFile(TransferId id);
             

Since: 2.2

Parameters:

  • id: Transaction ID of the file transfer request

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if the transaction ID is invalid.

    • 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:

 // Assume filetransfer object has been obtained by using getSAFileTransfer() method.
 var callback = {
     onreceive : function(transferId, fileName){
         try {
             console.log("Incoming file transfer request form the remote peer agent. transferId : " + transferId + " file name : " + fileName);
             filetransfer.receiveFile(transferId, newFilePath);
         } catch(e) {
             console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
         }
     },
     onprogress : function(transferId, progress){
         if(1) { // User wanted condition
             try {
                 filetransfer.cancelFile(transferId);
             } catch(e) {
                 console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
             }
         }
     },
     oncomplete : function(transferId, localPath){
         console.log("File transfer complete.  transferId : " + transferId);
     },
     onerror : function(errorCode, transferId){
         console.log("FileReceiveError  transferId : " + transferId + " code : " + errorCode);
     }
 };

 try {
     filetransfer.setFileReceiveListener(callback);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 
rejectFile
Rejects an incoming transfer request from a remote Accessory Peer Agent.
void rejectFile(TransferId id);
             

Since: 2.2

Parameters:

  • id: Transaction ID of the file transfer request

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if the transaction ID is invalid.

    • 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:

 // Assume filetransfer object has been obtained by using getSAFileTransfer() method.
 var callback = {
     onreceive : function(transferId, fileName){
         if(1) { // User wanted condition
             try {
                 filetransfer.rejectFile(transferId);
             } catch(e) {
                 console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
             }
         }
     },
     onprogress : function(transferId, progress){
         console.log("onprogress transferId : " + transferId + ", progress : " + progress);
     },
     oncomplete : function(transferId, localPath){
         console.log("File transfer complete.  transferId : " + transferId);
     },
     onerror : function(errorCode, transferId){
         console.log("FileReceiveError  transferId : " + transferId + " code : " + errorCode);
     }
 };

 try {
     filetransfer.setFileReceiveListener(callback);
 } catch(e) {
     console.log("Error Exception, error name : " + e.name + ", error message : " + e.message);
 }
 

2.10. SADataReceiveCallback

Called when data is received from a remote Accessory Peer Agent.
    [Callback=FunctionOnly, NoInterfaceObject]
    interface SADataReceiveCallback {
        void onreceive(SAChannelId channelId, DOMString data);
    };

Since: 2.2

Methods

onreceive
Called when data is received from a remote Accessory Peer Agent.
void onreceive(SAChannelId channelId, DOMString data);
             

Since: 2.2

Parameters:

  • channelId: Channel identifier on which the data is received
  • data: Received data string

2.11. SASocketStatusCallback

The callback function to be invoked when a Service Connection is lost.
    [Callback=FunctionOnly, NoInterfaceObject]
    interface SASocketStatusCallback {
        void onconnectionlost(SASocketStatusErrorCode reason);
    };

Since: 2.2

Methods

onconnectionlost
Called to indicate to the application that the Service Connection with a Accessory Peer Agent is lost.
void onconnectionlost(SASocketStatusErrorCode reason);
             

Since: 2.2

Parameters:

  • reason: Error code indicating the reason why the Service Connection with the Accessory Peer Agent is lost

2.12. SAFileReceiveCallback

The callback function to be invoked when receiving a file.
    [Callback, NoInterfaceObject] interface SAFileReceiveCallback {
        void onreceive(TransferId id, DOMString fileName);

        void onprogress(TransferId id, unsigned long progress);

        void oncomplete(TransferId id, DOMString localPath);

        void onerror(SAFileReceiveErrorCode errorCode, TransferId id);
    };

Since: 2.2

Methods

onreceive
Invoked on the receiver side when there is an incoming file transfer request from the sender. The receiver needs to be registered beforehand for the file transfer service to receive this callback.
void onreceive(TransferId id, DOMString fileName);
             

Since: 2.2

Parameters:

  • id: Transaction ID of the file transfer
  • fileName: File name of the incoming file transfer
onprogress
Provides the progress information.
void onprogress(TransferId id, unsigned long progress);
             

Since: 2.2

Parameters:

  • id: Transaction ID of the file transfer
  • progress: Progress percentage
oncomplete
Indicates that the file transfer is complete.
void oncomplete(TransferId id, DOMString localPath);
             

Since: 2.2

Parameters:

  • id: Transaction ID of the file transfer request
  • localPath: Path where the received file is stored
onerror
Invoked when an error occurs while receiving a file.
void onerror(SAFileReceiveErrorCode errorCode, TransferId id);
             

Since: 2.2

Parameters:

  • errorCode: Error code indicating the error type
  • id: Transaction ID of the file transfer

2.13. SAFileSendCallback

The callback function to be invoked when sending a file.
    [Callback, NoInterfaceObject] interface SAFileSendCallback {
        void onprogress(TransferId id, unsigned long progress);

        void oncomplete(TransferId id, DOMString localPath);

        void onerror(SAFileSendErrorCode errorCode, TransferId id);
    };

Since: 2.2

Methods

onprogress
Provides the progress information.
void onprogress(TransferId id, unsigned long progress);
             

Since: 2.2

Parameters:

  • id: Transaction ID of the file transfer
  • progress: Progress percentage
oncomplete
Indicates that the file transfer is complete.
void oncomplete(TransferId id, DOMString localPath);
             

Since: 2.2

Parameters:

  • id: Transaction ID of the file transfer
  • localPath: Path of the file that is sent
onerror
Invoked when an error occurs while sending a file.
void onerror(SAFileSendErrorCode errorCode, TransferId id);
             

Since: 2.2

Parameters:

  • errorCode: Error code indicating the error type
  • id: Transaction ID of the file transfer

2.14. SAAgentSuccessCallback

This callback function is invoked when the SAAgent object is successfully retrieved from the Accessory Service Profile.
    [Callback=FunctionOnly, NoInterfaceObject]
    interface SAAgentSuccessCallback {
        void onsuccess(SAAgent[] agents);
    };

Since: 2.2

Methods

onsuccess
Invoked when agents specified in the Service Profile are successfully retrieved.
void onsuccess(SAAgent[] agents);
             

Since: 2.2

Parameters:

  • agents: Available SAAgents defined in the Service Profile

2.15. SAPeerAgentFindCallback

This callback function is invoked when finding remote Accessory Peer Agents.
    [Callback, NoInterfaceObject]
    interface SAPeerAgentFindCallback {
        void onpeeragentfound(SAPeerAgent peerAgent);

        void onpeeragentupdated(SAPeerAgent peerAgent, PeerAgentStatus status);

        void onerror(SAPeerAgentFindErrorCode errorCode);
    };

Since: 2.2

Methods

onpeeragentfound
Called whenever a remote Accessory Peer Agent is found
void onpeeragentfound(SAPeerAgent peerAgent);
             

Since: 2.2

Parameters:

  • peerAgent: Found remote Accessory Peer Agent
onpeeragentupdated
This callback function is invoked to notify an application of a change in the status of a peer agent on a remote device. This callback is invoked only if a service discovery request has been previously initiated by a call to findPeerAgents(). The status of the discovered peer is contained in the result parameter of the callback and indicates the availability or unavailability of the peer agent. If there is more than one service agent for which the status is updated (on one or more connected Accessory Devices), this callback is invoked once for each peer service agent.
void onpeeragentupdated(SAPeerAgent peerAgent, PeerAgentStatus status);
             

Since: 2.2

Parameters:

  • peerAgent: Found remote Accessory Peer Agent
  • status: Changed status of the peer agent
onerror
Called when any kind of error occurs while finding remote Accessory Peer Agents.
void onerror(SAPeerAgentFindErrorCode errorCode);
             

Since: 2.2

Parameters:

  • errorCode: Error code indicating the error type

2.16. ServiceConnectionCallback

This callback function is invoked for sending notifications of connection request events.
    [Callback, NoInterfaceObject] interface ServiceConnectionCallback {
        void onrequest(SAPeerAgent peerAgent);

        void onconnect(SASocket socket);

        void onerror(SAServiceConnectionErrorCode errorCode);

        void onerror(SAServiceConnectionErrorCode errorCode, SAPeerAgent peerAgent);
    };

Since: 2.2

Methods

onrequest
Invoked when a remote Accessory Peer Agent requests for a Service Connection with an application.
void onrequest(SAPeerAgent peerAgent);
             

Since: 2.2

Application calls SAAgent.acceptServiceConnectionRequest() in this callback to accept a Service Connection request, or calls SAAgent.rejectServiceConnectionRequest() to reject it.

Parameters:

  • peerAgent: Remote SAPeer Agent that requests to connect with the SAAgent
onconnect
Invoked when a connection between a Service Provider and Service Consumer is established.
void onconnect(SASocket socket);
             

Since: 2.2

Parameters:

  • socket: The SASocket object that represents the Service Connection with a remote Accessory Peer Agent
onerror
Invoked when any kind of error occurs during a connect/request operation.
void onerror(SAServiceConnectionErrorCode errorCode);
             

Since: 2.2

Parameters:

  • errorCode: Error code indicating the error type
onerror
Invoked when any kind of error occurs during a connect/request operation.
void onerror(SAServiceConnectionErrorCode errorCode, SAPeerAgent peerAgent);
             

Since: 2.2.1.3

Parameters:

  • errorCode: Error code indicating the error type
  • peerAgent: Remote SAPeer Agent that an error has occurred

2.17. SADeviceStatusCallback

This callback function is invoked when a peer device is attached or detached.
    [Callback=FunctionOnly, NoInterfaceObject]
    interface SADeviceStatusCallback {
        void ondevicestatus(TransportType type, DeviceStatus status);
    };

Since: 2.2

Methods

ondevicestatus
Invoked when a peer device is attached or detached.
void ondevicestatus(TransportType type, DeviceStatus status);
             

Since: 2.2

Parameters:

  • type: Transport type which is either attached or detached
  • status: Current state of the connection with a peer device

2.18. SAAuthenticatePeerAgentSuccessCallback

This callback function is invoked when authentication information of remote peer are successfully returned.
    [Callback=FunctionOnly, NoInterfaceObject]
    interface SAAuthenticatePeerAgentSuccessCallback {
        void onsuccess(SAPeerAgent peerAgent, SAAuthenticationToken authToken);
    };

Since: 2.2

Application can verify remote peer agent's identity by checking its authentication token information, then decide whether to request a service connection with the remote peer agent, or whether to accept incoming service connection requests from the remote peer agent.

Methods

onsuccess
Invoked when authentication information of remote peer are successfully returned
void onsuccess(SAPeerAgent peerAgent, SAAuthenticationToken authToken);
             

Since: 2.2

Parameters:

  • peerAgent: Remote SAPeerAgent that requests to connect with the SAAgent
  • authToken: The authentication token of remote peer agent

2.19. SAMessageSendCallback

The callback function to be invoked when sending a message.
    [Callback, NoInterfaceObject] interface SAMessageSendCallback {
        void onsent(SAPeerAgent peerAgent, long id);

        void onerror(SAMessageSendErrorCode errorCode, SAPeerAgent peerAgent, long id);
    };

Since: 2.3.2

Methods

onsent
Invoked when the message is successfully sent .
void onsent(SAPeerAgent peerAgent, long id);
             

Since: 2.3.2

Parameters:

  • peerAgent: Remote Accessory Peer Agent to whom the message is delivered.
  • id: Id of the sending message. This can be matched with the value returned in SAMessage.sendData() or SAMessage.sendSecureData().
onerror
Invoked when an error occurs while sending a message.
void onerror(SAMessageSendErrorCode errorCode, SAPeerAgent peerAgent, long id);
             

Since: 2.3.2

Parameters:

  • errorCode: Error code indicating the error type
  • peerAgent: Remote Accessory Peer Agent to whom the message is delivered.
  • id: Id of the sending message. This can be matched with the value returned in SAMessage.sendData() or SAMessage.sendSecureData().

2.20. SAMessageReceiveCallback

Called when message is received from a remote Accessory Peer Agent.
    [Callback=FunctionOnly, NoInterfaceObject]
    interface SAMessageReceiveCallback {
        void onreceive(SAPeerAgent peerAgent, DOMString data);
    };

Since: 2.3.2

Methods

onreceive
Called when message is received from a remote Accessory Peer Agent.
void onreceive(SAPeerAgent peerAgent, DOMString data);
             

Since: 2.3.2

Parameters:

  • peerAgent: Remote Accessory Peer Agent to whom the message is delivered.
  • data: Received data string

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 SAP feature, define the following requirements in the config file:

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

    module SAPService {
    
        enum SARole {"PROVIDER", "CONSUMER"};
    
        enum TransportType {"TRANSPORT_BLE", "TRANSPORT_BT", "TRANSPORT_USB", "TRANSPORT_WIFI"};
    
        enum DeviceStatus {"ATTACHED", "DETACHED"};
    
        enum PeerAgentStatus {"AVAILABLE", "UNAVAILABLE"};
    
        enum AuthenticationType {"AUTHENTICATION_TYPE_NONE", "AUTHENTICATION_TYPE_CERTIFICATE_X509"};
    
        enum SAPeerAgentFindErrorCode {"PEER_NOT_FOUND", "DEVICE_NOT_CONNECTED", "DUPLICATE_REQUEST"};
    
        enum SAServiceConnectionErrorCode {"ALREADY_EXIST", "NETWORK_ERROR", "DEVICE_UNREACHABLE", "INVALID_PEERAGENT", "PEERAGENT_NO_RESPONSE", "PEERAGENT_REJECTED", "ERROR_REFLECTION_EXCEPTION"};
    
        enum SAFileSendErrorCode {"FILE_IO", "PEER_BUSY", "PEER_CHANNEL_IO", "PEER_CONN_LOST", "PEER_NO_RESPONSE", "PEER_REJECTED", "REQUEST_NOT_QUEUED", "SPACE_NOT_AVAILABLE", "UNKNOWN_ERROR"};
    
        enum SAFileReceiveErrorCode {"FILE_IO", "PEER_CHANNEL_IO", "PEER_CONN_LOST", "PEER_NO_RESPONSE", "PEER_REJECTED", "SPACE_NOT_AVAILABLE", "UNKNOWN_ERROR"};
    
        enum SASocketStatusErrorCode {"PEER_DISCONNECTED", "DEVICE_DETACHED", "UNKNOWN_REASON"};
    
        enum SAMessageSendErrorCode {"PEER_UNREACHABLE", "PEER_NO_RESPONSE", "UNKNOWN_ERROR"};
    
        enum SAFeatureType {"SOCKET", "MESSAGE"};
    
        typedef long TransferId;
    
        typedef long SAChannelId;
    
        [NoInterfaceObject] interface SAManagerObject {
            readonly attribute SAManager sa;
        };
        WebAPIs implements SAManagerObject;
    
        [NoInterfaceObject] interface SAManager {
            void requestSAAgent(SAAgentSuccessCallback successCallback, optional ErrorCallback? errorCallback);
    
            void setDeviceStatusListener(SADeviceStatusCallback callback);
        };
    
        [NoInterfaceObject] interface SAAgent {
            readonly attribute DOMString id;
    
            readonly attribute DOMString name;
    
            readonly attribute SARole role;
    
            readonly attribute SAChannelId[] channelIds;
    
            void requestServiceConnection(SAPeerAgent peerAgent);
    
            void setServiceConnectionListener(ServiceConnectionCallback callback);
    
            void authenticatePeerAgent(SAPeerAgent peerAgent, SAAuthenticatePeerAgentSuccessCallback successCallback, optional ErrorCallback? errorCallback);
    
            void acceptServiceConnectionRequest(SAPeerAgent peerAgent);
    
            void rejectServiceConnectionRequest(SAPeerAgent peerAgent);
    
            void findPeerAgents();
    
            void setPeerAgentFindListener(SAPeerAgentFindCallback callback);
    
            SAFileTransfer getSAFileTransfer();
    
            SAMessage getSAMessage();
        };
    
        [NoInterfaceObject] interface SAAuthenticationToken {
            readonly attribute AuthenticationType authenticationType;
    
            readonly attribute DOMString key;
        };
    
        [NoInterfaceObject] interface SAPeerAccessory {
            readonly attribute DOMString deviceAddress;
    
            readonly attribute DOMString deviceName;
    
            readonly attribute DOMString productId;
    
            readonly attribute TransportType transportType;
    
            readonly attribute DOMString vendorId;
    
            readonly attribute DOMString accessoryId;
        };
    
        [NoInterfaceObject] interface SAPeerAgent {
            readonly attribute SAPeerAccessory peerAccessory;
    
            readonly attribute DOMString appName;
    
            readonly attribute long maxAllowedDataSize;
    
            readonly attribute DOMString peerId;
    
            readonly attribute DOMString profileVersion;
    
            readonly attribute SAFeatureType[] feature;
        };
    
        [NoInterfaceObject] interface SAMessage {
            long sendData(SAPeerAgent peerAgent, DOMString data, SAMessageSendCallback callback);
    
            long sendSecureData(SAPeerAgent peerAgent, DOMString data, SAMessageSendCallback callback);
    
            void setMessageReceiveListener(SAMessageReceiveCallback callback);
        };
    
        [NoInterfaceObject] interface SASocket {
            readonly attribute SAPeerAgent peerAgent;
    
            void close();
    
            boolean isConnected();
    
            void sendData(SAChannelId channelId, DOMString data);
    
            void sendSecureData(SAChannelId channelId, DOMString data);
    
            void setDataReceiveListener(SADataReceiveCallback callback);
    
            void setSocketStatusListener(SASocketStatusCallback callback);
        };
    
        [NoInterfaceObject] interface SAFileTransfer {
    
            readonly attribute DOMString defaultReceivePath;
    
            long sendFile(SAPeerAgent peerAgent, DOMString filePath);
    
            void setFileSendListener(SAFileSendCallback callback);
    
            void setFileReceiveListener(SAFileReceiveCallback callback);
    
            void receiveFile(TransferId id, DOMString localPath);
    
            void cancelFile(TransferId id);
    
            void rejectFile(TransferId id);
        };
    
        [Callback=FunctionOnly, NoInterfaceObject]
        interface SADataReceiveCallback {
            void onreceive(SAChannelId channelId, DOMString data);
        };
    
        [Callback=FunctionOnly, NoInterfaceObject]
        interface SASocketStatusCallback {
            void onconnectionlost(SASocketStatusErrorCode reason);
        };
    
        [Callback, NoInterfaceObject] interface SAFileReceiveCallback {
            void onreceive(TransferId id, DOMString fileName);
    
            void onprogress(TransferId id, unsigned long progress);
    
            void oncomplete(TransferId id, DOMString localPath);
    
            void onerror(SAFileReceiveErrorCode errorCode, TransferId id);
        };
    
        [Callback, NoInterfaceObject] interface SAFileSendCallback {
            void onprogress(TransferId id, unsigned long progress);
    
            void oncomplete(TransferId id, DOMString localPath);
    
            void onerror(SAFileSendErrorCode errorCode, TransferId id);
        };
    
        [Callback=FunctionOnly, NoInterfaceObject]
        interface SAAgentSuccessCallback {
            void onsuccess(SAAgent[] agents);
        };
    
        [Callback, NoInterfaceObject]
        interface SAPeerAgentFindCallback {
            void onpeeragentfound(SAPeerAgent peerAgent);
    
            void onpeeragentupdated(SAPeerAgent peerAgent, PeerAgentStatus status);
    
            void onerror(SAPeerAgentFindErrorCode errorCode);
        };
    
        [Callback, NoInterfaceObject] interface ServiceConnectionCallback {
            void onrequest(SAPeerAgent peerAgent);
    
            void onconnect(SASocket socket);
    
            void onerror(SAServiceConnectionErrorCode errorCode);
    
            void onerror(SAServiceConnectionErrorCode errorCode, SAPeerAgent peerAgent);
        };
    
        [Callback=FunctionOnly, NoInterfaceObject]
        interface SADeviceStatusCallback {
            void ondevicestatus(TransportType type, DeviceStatus status);
        };
    
        [Callback=FunctionOnly, NoInterfaceObject]
        interface SAAuthenticatePeerAgentSuccessCallback {
            void onsuccess(SAPeerAgent peerAgent, SAAuthenticationToken authToken);
        };
    
        [Callback, NoInterfaceObject] interface SAMessageSendCallback {
            void onsent(SAPeerAgent peerAgent, long id);
    
            void onerror(SAMessageSendErrorCode errorCode, SAPeerAgent peerAgent, long id);
        };
    
        [Callback=FunctionOnly, NoInterfaceObject]
        interface SAMessageReceiveCallback {
            void onreceive(SAPeerAgent peerAgent, DOMString data);
        };
    };