public abstract class SAAgent extends Service
Both Service Provider and Service Consumer applications must declare a subclass of this class and implement the
actions of an Accessory Peer Agent (Service Provider or Service Consumer). The application has to add a
Broadcast Receiver into the Android Manifest file for ACTION_REGISTRATION_REQUIRED
action to register
an application to Samsung Accessory Service Framework and the ACTION_SERVICE_CONNECTION_REQUESTED
action to receive a service connection request.
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 String |
ACTION_REGISTRATION_REQUIRED
Broadcast Action: Indicates that an installed peer agent has been required to register.
|
static String |
ACTION_SERVICE_CONNECTION_REQUESTED
Broadcast Action: Indicates that an incoming service connection request from remote Accessory Peer Agent has
been received.
|
static int |
AUTHENTICATION_FAILURE_PEER_AGENT_NOT_SUPPORTED
The remote Accessory Peer Agent does not support authentication.
|
static int |
AUTHENTICATION_FAILURE_TOKEN_NOT_GENERATED
The remote Accessory Peer Agent's authentication token is not generated.
|
static int |
AUTHENTICATION_SUCCESS
Authentication request succeeded.
|
static int |
CONNECTION_ALREADY_EXIST
Service Connection establishment failed as another Service Connection request with the same remote Accessory
Peer Agent has been already established.
|
static int |
CONNECTION_DUPLICATE_REQUEST
Service Connection establishment failed as another attempt with same remote Accessory Peer Agent is still in
progress.
|
static int |
CONNECTION_FAILURE_DEVICE_UNREACHABLE
Service Connection establishment failed as the remote Accessory Peer Agent is unreachable.
|
static int |
CONNECTION_FAILURE_INVALID_PEERAGENT
Service Connection establishment failed as the
SAPeerAgent input argument is null or invalid. |
static int |
CONNECTION_FAILURE_NETWORK
Service Connection establishment failed due to network errors.
|
static int |
CONNECTION_FAILURE_PEERAGENT_NO_RESPONSE
Service Connection establishment failed as the remote Accessory Peer Agent does not give any response.
|
static int |
CONNECTION_FAILURE_PEERAGENT_REJECTED
Service Connection establishment failed as the remote Accessory Peer Agent rejected the request.
|
static int |
CONNECTION_FAILURE_SERVICE_LIMIT_REACHED
Service Connection establishment failed as the service limit set by the Accessory Peer Agent has been
reached.
|
static int |
CONNECTION_SUCCESS
Service Connection has been established successfully.
|
static int |
ERROR_CONNECTION_INVALID_PARAM
Data kept by Samsung Accessory Service Framework was lost and cannot be recovered from this error in
runtime.
|
static int |
ERROR_FATAL
Fatal error occurred such as binding failure or if the Samsung Accessory Service Framework has stopped.
|
static int |
ERROR_PERMISSION_DENIED
Binding to Samsung Accessory Service failed due to permission issue.
|
static int |
ERROR_PERMISSION_FAILED
Binding to Samsung Accessory Service failed due to permission mismatch.
|
static int |
ERROR_SDK_NOT_INITIALIZED
Samsung Accessory SDK is not initialized.
|
static int |
FINDPEER_DEVICE_NOT_CONNECTED
Accessory Devices are not connected.
|
static int |
FINDPEER_DUPLICATE_REQUEST
Another request to find an Accessory Peer Agent calling
findPeerAgents() is still in progress. |
static int |
FINDPEER_SERVICE_NOT_FOUND
No matching Accessory Peer Agents exist on connected Accessory Devices.
|
static int |
PEER_AGENT_AVAILABLE
Accessory Peer Agents have been available on a remote Accessory Device.
|
static int |
PEER_AGENT_FOUND
Accessory Peer Agents have been found.
|
static int |
PEER_AGENT_UNAVAILABLE
Accessory Peer Agents have been unavailable on a remote Accessory Device.
|
Modifier | Constructor and Description |
---|---|
protected |
SAAgent(String name)
Creates an SAAgent instance with the specified name.
|
protected |
SAAgent(String name,
Class<? extends SASocket> socketClass)
Creates an SAAgent instance with the specified name and the derived subclass of
SASocket . |
Modifier and Type | Method and Description |
---|---|
protected void |
acceptServiceConnectionRequest(SAPeerAgent peerAgent)
Accepts a Service Connection request from the remote Accessory Peer Agent.
|
protected void |
authenticatePeerAgent(SAPeerAgent peerAgent)
Authenticates an Accessory Peer Agent.
|
protected void |
findPeerAgents()
Finds matching Accessory Peer Agents.
|
int |
getServiceChannelId(int index)
Gets the service channel ID at the specific index of the list that is declared in the Service Profile XML.
|
int |
getServiceChannelSize()
Gets the size of the service channel list that is declared in the Service Profile XML.
|
String |
getServiceProfileId()
Gets the service profile ID that is declared in the Service Profile XML.
|
String |
getServiceProfileName()
Gets the service profile name that is declared in the Service Profile XML.
|
protected void |
onAuthenticationResponse(SAPeerAgent peerAgent,
SAAuthenticationToken authToken,
int code)
Called when the Accessory Peer Agent authentication is completed.
|
protected void |
onError(SAPeerAgent peerAgent,
String errorMessage,
int errorCode)
Called when an SAAgent error occurs in Samsung Accessory Service Framework.
|
protected void |
onError(String errorMessage,
int errorCode)
Deprecated.
Use
onError(SAPeerAgent, String, int) instead. |
protected void |
onFindPeerAgentResponse(SAPeerAgent peerAgent,
int result)
Deprecated.
use
onFindPeerAgentsResponse(SAPeerAgent[], int) instead. |
protected void |
onFindPeerAgentsResponse(SAPeerAgent[] peerAgents,
int result)
Called when the discovery for matching Accessory Peer Agents is completed.
|
protected void |
onPeerAgentsUpdated(SAPeerAgent[] peerAgents,
int result)
Called when the status of remote Accessory Peer Agent on a connected remote Accessory Devices changes.
|
protected void |
onPeerAgentUpdated(SAPeerAgent peerAgent,
int result)
Deprecated.
use
onPeerAgentsUpdated(SAPeerAgent[], int) instead. |
protected void |
onServiceConnectionRequested(SAPeerAgent peerAgent)
Called when a remote Accessory Peer Agent requests a Service Connection.
|
protected void |
onServiceConnectionResponse(SAPeerAgent peerAgent,
SASocket socket,
int result)
Called when a Service Connection to a remote Accessory Peer Agent is established or failed.
|
protected void |
onServiceConnectionResponse(SASocket socket,
int result)
Deprecated.
|
protected void |
rejectServiceConnectionRequest(SAPeerAgent peerAgent)
Rejects a Service Connection request from the remote Accessory Peer Agent.
|
protected void |
requestServiceConnection(SAPeerAgent peerAgent)
Requests a Service Connection with a remote Accessory Peer Agent.
|
public static final int PEER_AGENT_FOUND
Constant Value: 0 (0x00000000)
onFindPeerAgentsResponse(SAPeerAgent[], int)
,
onFindPeerAgentResponse(SAPeerAgent, int)
,
Constant Field Valuespublic static final int PEER_AGENT_AVAILABLE
Constant Value: 1 (0x00000001)
onPeerAgentsUpdated(SAPeerAgent[], int)
,
onPeerAgentUpdated(SAPeerAgent, int)
,
Constant Field Valuespublic static final int PEER_AGENT_UNAVAILABLE
Constant Value: 2 (0x00000002)
onPeerAgentsUpdated(SAPeerAgent[], int)
,
onPeerAgentUpdated(SAPeerAgent, int)
,
Constant Field Valuespublic static final int FINDPEER_SERVICE_NOT_FOUND
Constant Value: 1794 (0x00000702)
onFindPeerAgentsResponse(SAPeerAgent[], int)
,
onFindPeerAgentResponse(SAPeerAgent, int)
,
Constant Field Valuespublic static final int FINDPEER_DEVICE_NOT_CONNECTED
Constant Value: 1793 (0x00000701)
onFindPeerAgentsResponse(SAPeerAgent[], int)
,
onFindPeerAgentResponse(SAPeerAgent, int)
,
Constant Field Valuespublic static final int FINDPEER_DUPLICATE_REQUEST
findPeerAgents()
is still in progress.
Constant Value: 3085 (0x00000C0D)
onFindPeerAgentsResponse(SAPeerAgent[], int)
,
onFindPeerAgentResponse(SAPeerAgent, int)
,
Constant Field Valuespublic static final int CONNECTION_SUCCESS
Constant Value: 0 (0x00000000)
public static final int ERROR_CONNECTION_INVALID_PARAM
Constant Value: 1025 (0x00000401)
onError(String, int)
,
onError(SAPeerAgent, String, int)
,
Constant Field Valuespublic static final int CONNECTION_FAILURE_DEVICE_UNREACHABLE
Constant Value: 1028 (0x00000404)
public static final int CONNECTION_ALREADY_EXIST
Constant Value: 1029 (0x00000405)
public static final int CONNECTION_FAILURE_PEERAGENT_NO_RESPONSE
Constant Value: 1030 (0x00000406)
public static final int CONNECTION_FAILURE_PEERAGENT_REJECTED
Constant Value: 1031 (0x00000407)
public static final int CONNECTION_FAILURE_INVALID_PEERAGENT
SAPeerAgent
input argument is null or invalid.
Constant Value: 1033 (0x00000409)
public static final int CONNECTION_DUPLICATE_REQUEST
Constant Value: 1040 (0x00000410)
public static final int CONNECTION_FAILURE_SERVICE_LIMIT_REACHED
Constant Value: 1037 (0x0000040D)
public static final int CONNECTION_FAILURE_NETWORK
Constant Value: 1280 (0x00000500)
public static final int AUTHENTICATION_SUCCESS
Constant Value: 0 (0x00000000)
onAuthenticationResponse(SAPeerAgent, SAAuthenticationToken, int)
,
Constant Field Valuespublic static final int AUTHENTICATION_FAILURE_TOKEN_NOT_GENERATED
Constant Value: 1545 (0x00000609)
onAuthenticationResponse(SAPeerAgent, SAAuthenticationToken, int)
,
Constant Field Valuespublic static final int AUTHENTICATION_FAILURE_PEER_AGENT_NOT_SUPPORTED
Constant Value: 1546 (0x00000610)
onAuthenticationResponse(SAPeerAgent, SAAuthenticationToken, int)
,
Constant Field Valuespublic static final int ERROR_FATAL
Constant Value: 2048 (0x00000800)
onError(String, int)
,
onError(SAPeerAgent, String, int)
,
Constant Field Valuespublic static final int ERROR_SDK_NOT_INITIALIZED
SA.initialize(android.content.Context)
to initialize the Samsung Accessory SDK
before using it.
Constant Value: 2049 (0x00000801)
onError(String, int)
,
onError(SAPeerAgent, String, int)
,
Constant Field Valuespublic static final int ERROR_PERMISSION_DENIED
Constant Value: 2304 (0x00000900)
onError(String, int)
,
onError(SAPeerAgent, String, int)
,
Constant Field Valuespublic static final int ERROR_PERMISSION_FAILED
Constant Value: 2305 (0x00000901)
onError(String, int)
,
onError(SAPeerAgent, String, int)
,
Constant Field Valuespublic static final String ACTION_SERVICE_CONNECTION_REQUESTED
Note:The designated broadcast receiver, "com.samsung.android.sdk.accessory.ServiceConnectionIndicationBroadcastReceiver" must be registered in the receiving application's manifest file.
<application
...
<receiver android:name="com.samsung.android.sdk.accessory.ServiceConnectionIndicationBroadcastReceiver" >
<intent-filter>
<action android:name="com.samsung.accessory.action.SERVICE_CONNECTION_REQUESTED" />
</intent-filter>
</receiver>
...
</application>
Constant Value: "com.samsung.accessory.action.SERVICE_CONNECTION_REQUESTED"
public static final String ACTION_REGISTRATION_REQUIRED
Note:The designated broadcast receiver, "com.samsung.android.sdk.accessory.RegisterUponInstallReceiver" must be registered in the receiving application's manifest file.
<application
...
<receiver android:name="com.samsung.android.sdk.accessory.RegisterUponInstallReceiver">
<intent-filter>
<action android:name="com.samsung.accessory.action.REGISTER_AGENT"/>
</intent-filter>
</receiver>
...
</application>
Constant Value: "com.samsung.accessory.action.REGISTER_AGENT"
protected SAAgent(String name, Class<? extends SASocket> socketClass)
SASocket
.
Note: All Service Provider and Service Consumer applications must implement the public default constructor and never call it. The constructor is dynamically referenced by Samsung Accessory SDK.
protected SAAgent(String name)
Note: All Service Provider and Service Consumer applications must
implement the public default constructor and never call it. The constructor is dynamically referenced by Samsung
Accessory SDK. Your application must use this constructor if it makes use of only Message Service feature.
Use SAAgent(String, Class)
if it makes use of both Service Connection
and Message Service feature.
name
- The name for the derived subclass that extends SAAgent
base class.@Deprecated protected void onFindPeerAgentResponse(SAPeerAgent peerAgent, int result)
onFindPeerAgentsResponse(SAPeerAgent[], int)
instead.Application should handle this callback properly according to result code.
Note: This method is called from the worker thread. Spawn a separate thread if you need to do any heavy lifting in this callback.
peerAgent
- The instance of SAAgent
if found or null otherwise.result
- The result code. See PEER_AGENT_FOUND
, FINDPEER_DEVICE_NOT_CONNECTED
,
FINDPEER_SERVICE_NOT_FOUND
, FINDPEER_DUPLICATE_REQUEST
.findPeerAgents()
protected void onFindPeerAgentsResponse(SAPeerAgent[] peerAgents, int result)
Application should handle this callback properly according to result code.
Note: This method is called from the worker thread. Spawn a separate thread if you need to do any heavy lifting in this callback.
peerAgents
- The list of SAPeerAgent
instance, if found or null otherwise.result
- The result code. See PEER_AGENT_FOUND
, FINDPEER_DEVICE_NOT_CONNECTED
,
FINDPEER_SERVICE_NOT_FOUND
, FINDPEER_DUPLICATE_REQUEST
.findPeerAgents()
@Deprecated protected void onPeerAgentUpdated(SAPeerAgent peerAgent, int result)
onPeerAgentsUpdated(SAPeerAgent[], int)
instead.findPeerAgents()
.
If more than one Peer Agents have updated status (on one or more connected Accessory Devices), this callback is invoked once for each Accessory Peer Agent.
Note: Your application can cache the remote Accessory Peer Agents that are notified
in the callback with the result code PEER_AGENT_AVAILABLE
. However, in that case, your application
must handle the PEER_AGENT_UNAVAILABLE
result code correctly. By caching the result of a peer agent
discovery request, you can skip subsequent Accessory Peer Agents discovery requests until this callback
shows with the result code PEER_AGENT_UNAVAILABLE
.
Note: This method is called from worker thread. Spawn a separate thread if you need to do any heavy lifting in this callback.
peerAgent
- The instance of SAAgent
that represents the remote Accessory Peer Agent.result
- The changed status of the remote Accessory Peer Agent. See PEER_AGENT_AVAILABLE
,
PEER_AGENT_UNAVAILABLE
.protected void onPeerAgentsUpdated(SAPeerAgent[] peerAgents, int result)
findPeerAgents()
.
If more than one Peer Agents have updated status (on one or more connected Accessory Devices), this callback is invoked with a list of Peer Agents.
Note: Your application can cache the remote Accessory Peer Agents that are notified
in the callback with the result code PEER_AGENT_AVAILABLE
. However, in that case, your application
must handle the PEER_AGENT_UNAVAILABLE
result code correctly. By caching the result of a peer agent
discovery request, you can skip subsequent Accessory Peer Agents discovery requests until this callback
shows with the result code PEER_AGENT_UNAVAILABLE
.
Note: This method is called from worker thread. Spawn a separate thread if you need to do any heavy lifting in this callback.
peerAgents
- The list of SAPeerAgent
instance representing the remote Accessory Peer Agents.result
- The changed status of the remote Accessory Peer Agent. See PEER_AGENT_AVAILABLE
,
PEER_AGENT_UNAVAILABLE
.protected void onServiceConnectionRequested(SAPeerAgent peerAgent)
If your application is not running, Samsung Accessory Service Framework invokes your application when a Service Connection request arrives from an Accessory Peer Agent. Your application can handle the Service Connection request from the remote Accessory Peer Agent.
If you want to decide whether to accept or reject a Service Connection request, your application can
override this method and call acceptServiceConnectionRequest(SAPeerAgent)
to accept the Service
Connection request, or call rejectServiceConnectionRequest(SAPeerAgent)
to reject it.
peerAgent
- The instance of SAAgent
that represents the remote Accessory Peer Agent that requests a
Service Connection.@Deprecated protected void onServiceConnectionResponse(SASocket socket, int result)
onServiceConnectionResponse(SAPeerAgent, SASocket, int)
instead.requestServiceConnection(SAPeerAgent)
having been called.
If a Service Connection is established successfully, the SASocket
object is passed. It allows the
Service Provider or Service Consumer application to send and receive data from a connected Accessory Peer
Agent, as well as receive Service Connection related events.
Note: This method is called from the worker thread. Spawn a separate thread if you need to
do any heavy lifting in this callback. Don't call super.onServiceConnectionResponse(SASocket, int)
.
socket
- The instance of SASocket
if the Service Connection is successfully established or null
otherwise.result
- The result code corresponding to CONNECTION_* value.requestServiceConnection(SAPeerAgent)
protected void onServiceConnectionResponse(SAPeerAgent peerAgent, SASocket socket, int result)
requestServiceConnection(SAPeerAgent)
having been called.
If a Service Connection is established successfully, the SASocket
object is passed. It allows the
Service Provider or Service Consumer application to send and receive data from a connected Accessory Peer
Agent, as well as receive Service Connection related events.
Note: This method is called from the worker thread. Spawn a separate thread if you need to
do any heavy lifting in this callback. Don't call
super.onServiceConnectionResponse(SAPeerAgent, SASocket, int)
.
peerAgent
- The instance of SAAgent
that represents the remote Accessory Peer Agent.socket
- The instance of SASocket
if the Service Connection is successfully established or null
otherwise.result
- The result code corresponding to CONNECTION_* value.requestServiceConnection(SAPeerAgent)
protected void onAuthenticationResponse(SAPeerAgent peerAgent, SAAuthenticationToken authToken, int code)
Note: This method may not work properly depending on the firmware version of the accessory device. It is recommended to upgrade accessory device firmware if possible.
peerAgent
- The instance of SAAgent
that represents the authenticated remote Accessory Peer Agent.authToken
- The instance of SAAuthenticationToken
contains its authentication information.code
- The result code corresponding to AUTHENTICATION_* value.authenticatePeerAgent(SAPeerAgent)
@Deprecated protected void onError(String errorMessage, int errorCode)
onError(SAPeerAgent, String, int)
instead.Note: Implement error handling by overriding this method.
errorMessage
- The error messageerrorCode
- The error code corresponding to ERROR_* value.protected void onError(SAPeerAgent peerAgent, String errorMessage, int errorCode)
Note: Implement error handling by overriding this method.
peerAgent
- The instance of SAAgent
that represents the remote Accessory Peer Agent.errorMessage
- The error messageerrorCode
- The error code corresponding to ERROR_* value.protected final void findPeerAgents()
Application should listen for the result of finding Accessory Peer Agent using
onFindPeerAgentResponse(SAPeerAgent, int)
callback. If multiple matching Accessory Peer Agents are
found, the onFindPeerAgentResponse(SAPeerAgent, int)
callback is invoked multiple times, one for
each.
protected final void requestServiceConnection(SAPeerAgent peerAgent)
The application should listen for the result of a Service Connection request using
onServiceConnectionResponse(SAPeerAgent, SASocket, int)
callback.
Note: Ensure the availability of the Accessory Peer Agent before calling this method. This
method is typically called in the onFindPeerAgentResponse(SAPeerAgent, int)
callback. You should
NOT use the previously cached SAPeerAgent
instance, as it may be no longer available for making
Service Connection with.
peerAgent
- The instance of SAAgent
that represents the remote Accessory Peer Agent whom requests Service
Connection to.IllegalArgumentException
- Thrown if peerAgent argument passed is null or invalid.protected void acceptServiceConnectionRequest(SAPeerAgent peerAgent)
Application should listen for the result of accepting Service Connection using
onServiceConnectionResponse(SAPeerAgent, SASocket, int)
callback.
Note: This method can be called in the implementation of
onAuthenticationResponse(SAPeerAgent, SAAuthenticationToken, int)
or
onServiceConnectionRequested(SAPeerAgent)
callback.
peerAgent
- The instance of SAAgent
that represents the remote Accessory Peer Agent whose incoming
Service Connection requests.IllegalArgumentException
- Thrown if the peerAgent argument passed is null or invalid.protected void rejectServiceConnectionRequest(SAPeerAgent peerAgent)
The application should listen for the result of a Service Connection rejection using
onServiceConnectionResponse(SAPeerAgent, SASocket, int)
callback.
Note: This method can be called in the implementation of
onAuthenticationResponse(SAPeerAgent, SAAuthenticationToken, int)
or
onServiceConnectionRequested(SAPeerAgent)
callback.
peerAgent
- The instance of SAAgent
that represents the remote Accessory Peer Agent whose incoming
Service Connection requests.IllegalArgumentException
- Thrown if the peerAgent argument is null or invalid.protected void authenticatePeerAgent(SAPeerAgent peerAgent)
The application should listen for the result of an Accessory Peer Agent authentication using
onAuthenticationResponse(SAPeerAgent, SAAuthenticationToken, int)
callback.
Note: This method may not be working properly depending on the firmware version of accessory device. It is recommended to upgrade accessory device firmware if possible.
peerAgent
- The instance of SAAgent
represents the remote Accessory Peer Agent to be authenticated.IllegalArgumentException
- Thrown if the peerAgent argument passed is null or invalid.public String getServiceProfileId()
public String getServiceProfileName()
public int getServiceChannelSize()
This method can be used to know how many channels in the local agent.
So, using this method, you can call getServiceChannelId(int)
within a valid range of indexes.
public int getServiceChannelId(int index)
This method can be used for sending messages to peer agents through SASocket.send(int, byte[])
method.
You can use its return value as the service channel ID for the argument of SASocket.send(int, byte[])
.
index
- The index of channel ID in the service channel list. It starts from index 0Copyright © Samsung Electronics, Co., Ltd. All rights reserved.