Overview Package Class Tree Deprecated Index Help
com.samsung.android.sdk.accessory

Class SASocket

  • java.lang.Object
    • com.samsung.android.sdk.accessory.SASocket

  • public abstract class SASocket
extends java.lang.Object
    SASocket represents an instance of a Service Connection between a Service Provider and a Service Consumer.

    Developer Guides

    Both Service Provider and Service Consumer applications must declare a subclass of SAAgent. The Service Connection, represented by this class, is the dialogue between the two SAAgent objects.

    The objects of this class are created when a successful Service Connection is established. Both Service Provider and Service Consumer application must declare a subclass of this class, and implement the Service Connection related event handling methods: onReceive(int, byte[]), onError(int, String, int), and onServiceConnectionLost(int).

    Both Service Provider and Service Consumer application can simply call send(int, byte[]) to write on a channel inside the Service Connection. They can also call close() to terminate the Service Connection with the remote Accessory Peer Agent.

    Note: Both Service Provider and Service Consumer application must register a concrete implementation of this class with SAAgent by passing the name and derived concrete class as the parameters of SAAgent constructor. An instance of this class is passed to the SAAgent object in the SAAgent.onServiceConnectionResponse(SAPeerAgent, SASocket, int) callback, once the Service Connection is established with the remote Accessory Peer Agent. The application must also implement the public default constructor of this class, as follows: 

    
 

 public YourSubclassExtendsThisClass() {

     super("the name of your subclass extends this class");

 }

    The constructor is dynamically referenced by Samsung Accessory SDK. The application should never call the constructor.

    When you build your application in release mode, you must add several -keep lines in the ProGuard configuration file of your application to prevent ProGuard from renaming your subclasses of SAAgent and SASocket. (ProGuard is a tool integrated into the Android build system that obfuscates the code by renaming its classes and methods.)

    For more information about How to configure ProGuard, please visit the ProGuard page of Android Development Site.

    For more information about using Accessory, please refer to the Accessory Programming Guide.

    • Constructor Summary

      Constructors 
      Modifier Constructor and Description
      protected SASocket(java.lang.String name)
      Creates an SASocket instance.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method and Description
      void close()
      Closes the Service Connection with the remote Accessory Peer Agent.
      SAPeerAgent getConnectedPeerAgent()
      Returns the instance of the currently connected SAPeerAgent.
      boolean isConnected()
      Returns the status of the underlying Service Connection.
      abstract void onError(int channelId, java.lang.String errorMessage, int errorCode)
      Called when an error occurs.
      abstract void onReceive(int channelId, byte[] data)
      Called when a data is received from the remote Accessory Peer Agent.
      protected abstract void onServiceConnectionLost(int reason)
      Called when the Service Connection is lost with the remote Accessory Peer Agent by a hard loss of the network or when graceful Service Connection termination ends.
      void secureSend(int channelId, byte[] data)
      Sends encrypted data to a remote Accessory Peer Agent.
      void send(int channelId, byte[] data)
      Sends data to a remote Accessory Peer Agent.

    • Field Detail

      • CONNECTION_LOST_UNKNOWN_REASON

        public static final int CONNECTION_LOST_UNKNOWN_REASON
        Service Connection lost as unspecified error is occurred by Samsung Accessory Service Framework.

        Constant Value: 512 (0x00000200)

        Since:
        2.0.19
        See Also:
        onServiceConnectionLost(int), Constant Field Values

      • CONNECTION_LOST_PEER_DISCONNECTED

        public static final int CONNECTION_LOST_PEER_DISCONNECTED
        Service Connection lost as the remote Accessory Peer Agent closed the Service Connection. This is a graceful termination initiated by the remote Accessory Peer Agent.

        Constant Value: 513 (0x00000201)

        Since:
        2.0.19
        See Also:
        onServiceConnectionLost(int), Constant Field Values

      • CONNECTION_LOST_DEVICE_DETACHED

        public static final int CONNECTION_LOST_DEVICE_DETACHED
        Service Connection lost as the Accessory Device was detached.

        Constant Value: 521 (0x00000209)

        Since:
        2.0.19
        See Also:
        onServiceConnectionLost(int), Constant Field Values

      • CONNECTION_LOST_RETRANSMISSION_FAILED

        public static final int CONNECTION_LOST_RETRANSMISSION_FAILED
        Service Connection lost as it required retransmission. Since all retransmission trials failed, Samsung Accessory Service Framework terminated the Service Connection because it cannot meet the reliable transfer requirement.

        Constant Value: 522 (0x0000020A)

        Since:
        2.0.19
        See Also:
        onServiceConnectionLost(int), Constant Field Values

      • ERROR_FATAL

        public static final int ERROR_FATAL
        Service Connection lost as binding with Samsung Accessory Service Framework has stopped unexpectedly. This SASocket no longer represents a valid service connection.

        Constant Value: 2048 (0x00000800)

        Since:
        2.0.19
        See Also:
        onServiceConnectionLost(int), Constant Field Values

    • Constructor Detail

      • SASocket

        protected SASocket(java.lang.String name)
        Creates an SASocket instance. Implement the public default constructor as follows for Java Reflection purposes. 
         

 super("The name of the subclass that extends SASocket");
        Parameters:
        name - The name of the subclass that extends SASocket.
        Since:
        2.0.19

    • Method Detail

      • onError

        public abstract void onError(int channelId,
                             java.lang.String errorMessage,
                             int errorCode)
        Called when an error occurs. The application should implement error handling mechanisms in this method.
        Parameters:
        channelId - The channel ID.
        errorMessage - The error message.
        errorCode - The error code corresponding to ERROR_*.
        Since:
        2.0.19

      • onReceive

        public abstract void onReceive(int channelId,
                               byte[] data)
        Called when a data is received from the remote Accessory Peer Agent. The application should implement this method to handle the received data properly in order to realize the application's use cases.
        Parameters:
        channelId - The ID of the Service Channel on which the data is received.
        data - The byte array of the data received.
        Since:
        2.0.19

      • onServiceConnectionLost

        protected abstract void onServiceConnectionLost(int reason)
        Called when the Service Connection is lost with the remote Accessory Peer Agent by a hard loss of the network or when graceful Service Connection termination ends.

        The application should implement the service connection loss handling mechanism properly. For example, stop sending data on the Service Channels.

        Note: If you want to restore Service Connection, it is the application's responsibility to call SAAgent.findPeerAgents() to try to find the remote Accessory Peer Agent again and SAAgent.requestServiceConnection(SAPeerAgent) to establish Service Connection again.

        Parameters:
        reason - The reason for service connection loss corresponding to CONNECTION_LOST_* or ERROR_FATAL.
        Since:
        2.0.19

      • isConnected

        public boolean isConnected()
        Returns the status of the underlying Service Connection.
        Returns:
        true if an active Service Connection exists, false if the Service Connection has been terminated.
        Since:
        2.0.19

      • getConnectedPeerAgent

        public SAPeerAgent getConnectedPeerAgent()
        Returns the instance of the currently connected SAPeerAgent.

        It encapsulates the information of the connected remote Accessory Peer Agent and the Accessory Device that the Accessory Peer Agent runs on. For the Accessory Peer Agent, the information includes, for example, the version of Service Profile that the Accessory Peer Agent follows and the application name. For the Accessory Device, the information includes, for example, vendor ID, product ID, and device name.

        Returns:
        The instance of SAPeerAgent which encapsulates the information of the connected remote Accessory Peer Agent.
        Since:
        2.0.19

      • send

        public void send(int channelId,
                 byte[] data)
          throws java.io.IOException
        Sends data to a remote Accessory Peer Agent.

        At first, the application must specify on which Service Channel to send data. For example, the Accessory Service Profile can specify two Service Channels in the Service Connection, one for commands and the other for data.

        Note: This method is a blocking call. If you need to do any heavy lifting or long latency work in this callback, spawn a separate thread. DO NOT invoke this method on the main thread of the application. It processes the byte array completely before returning. DO NOT send a byte array bigger than SAPeerAgent.getMaxAllowedDataSize().

        Parameters:
        channelId - The ID of the Service Channel for sending data, specified in Accessory Service Profile XML file.
        data - The byte array of the data to be sent.
        Throws:
        java.io.IOException - Thrown if an I/O-related error occurs while sending data.
        java.lang.IllegalArgumentException - Thrown if any argument is invalid.
        Since:
        2.0.19

      • secureSend

        public void secureSend(int channelId,
                       byte[] data)
                throws java.io.IOException
        Sends encrypted data to a remote Accessory Peer Agent.

        At first, the application must specify on which Service Channel to send data. For example, the Accessory Service Profile can specify two Service Channels in the Service Connection, one for commands and the other for data.

        Note: This method is a blocking call. If you need to do any heavy lifting or long latency work in this callback, spawn a separate thread. DO NOT invoke this method on main thread of the application. It processes the byte array completely before returning. DO NOT send byte array bigger than SAPeerAgent.getMaxAllowedDataSize().

        Parameters:
        channelId - The ID of the Service Channel for sending data, specified in Accessory Service Profile XML file.
        data - The byte array of the data to be sent.
        Throws:
        java.io.IOException - Thrown if an I/O-related error occurs while sending data.
        java.lang.IllegalArgumentException - Thrown if any argument is invalid.
        Since:
        2.0.19

      • close

        public void close()
        Closes the Service Connection with the remote Accessory Peer Agent.

        The application cannot reconnect to this Service Connection afterwards, so it has to establish new Service Connection as needed. The Service Channels configured from the Accessory Service Profile XML during the Service Connection are considered to be closed once the Service Connection is closed.

        The SASocket is closed, and all relevant Service Channels are also lost.

        Since:
        2.0.19