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 twoSAAgent
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)
, andonServiceConnectionLost(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 callclose()
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 ofSAAgent
constructor. An instance of this class is passed to theSAAgent
object in theSAAgent.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
andSASocket
. (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.
-
-
Field Summary
Fields Modifier and Type Field and Description static int
CONNECTION_LOST_DEVICE_DETACHED
Service Connection lost as the Accessory Device was detached.static int
CONNECTION_LOST_PEER_DISCONNECTED
Service Connection lost as the remote Accessory Peer Agent closed the Service Connection.static int
CONNECTION_LOST_RETRANSMISSION_FAILED
Service Connection lost as it required retransmission.static int
CONNECTION_LOST_UNKNOWN_REASON
Service Connection lost as unspecified error is occurred by Samsung Accessory Service Framework.static int
ERROR_FATAL
Service Connection lost as binding with Samsung Accessory Service Framework has stopped unexpectedly.
-
Constructor Summary
Constructors Modifier Constructor and Description protected
SASocket(java.lang.String name)
Creates anSASocket
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 connectedSAPeerAgent
.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. ThisSASocket
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 anSASocket
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 extendsSASocket
.- 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 andSAAgent.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 connectedSAPeerAgent
.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
-
-