public abstract class SASocket
extends java.lang.Object
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.
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.
|
Modifier | Constructor and Description |
---|---|
protected |
SASocket(java.lang.String name)
Creates an
SASocket instance. |
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.
|
public static final int CONNECTION_LOST_UNKNOWN_REASON
Constant Value: 512 (0x00000200)
onServiceConnectionLost(int)
,
Constant Field Valuespublic static final int CONNECTION_LOST_PEER_DISCONNECTED
Constant Value: 513 (0x00000201)
onServiceConnectionLost(int)
,
Constant Field Valuespublic static final int CONNECTION_LOST_DEVICE_DETACHED
Constant Value: 521 (0x00000209)
onServiceConnectionLost(int)
,
Constant Field Valuespublic static final int CONNECTION_LOST_RETRANSMISSION_FAILED
Constant Value: 522 (0x0000020A)
onServiceConnectionLost(int)
,
Constant Field Valuespublic static final int ERROR_FATAL
SASocket
no longer represents a valid service connection.
Constant Value: 2048 (0x00000800)
onServiceConnectionLost(int)
,
Constant Field Valuesprotected SASocket(java.lang.String name)
SASocket
instance. Implement the public default constructor as follows for Java
Reflection purposes.
super("The name of the subclass that extends SASocket");
name
- The name of the subclass that extends SASocket
.public abstract void onError(int channelId, java.lang.String errorMessage, int errorCode)
channelId
- The channel ID.errorMessage
- The error message.errorCode
- The error code corresponding to ERROR_*.public abstract void onReceive(int channelId, byte[] data)
channelId
- The ID of the Service Channel on which the data is received.data
- The byte array of the data received.protected abstract void onServiceConnectionLost(int reason)
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.
reason
- The reason for service connection loss corresponding to CONNECTION_LOST_* or ERROR_FATAL.public boolean isConnected()
true
if an active Service Connection exists, false
if the Service Connection has
been terminated.public SAPeerAgent getConnectedPeerAgent()
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.
public void send(int channelId, byte[] data) throws java.io.IOException
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()
.
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.java.io.IOException
- Thrown if an I/O-related error occurs while sending data.java.lang.IllegalArgumentException
- Thrown if any argument is invalid.public void secureSend(int channelId, byte[] data) throws java.io.IOException
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()
.
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.java.io.IOException
- Thrown if an I/O-related error occurs while sending data.java.lang.IllegalArgumentException
- Thrown if any argument is invalid.public void close()
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.
Copyright © Samsung Electronics, Co., Ltd. All rights reserved.