public abstract class SAAgentV2
extends java.lang.Object
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
SAAgentV2
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 | Class and Description |
---|---|
static interface |
SAAgentV2.RequestAgentCallback
Callback interface for
requestAgent(Context, String, RequestAgentCallback) to receive SAAgentV2 instance. |
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
ACTION_REGISTRATION_REQUIRED
Broadcast Action: Indicates that an installed peer agent has been required to register.
|
static java.lang.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_AGENT_REQUEST_IN_PROGRESS
Requested Agent Class is being released.
|
static int |
ERROR_CLASS_NOT_FOUND
Requested Agent Class is not found.
|
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_CONSTRUCTOR_EXCEPTION
Requested Agent Class constructor threw an exception.
|
static int |
ERROR_CONSTRUCTOR_NOT_FOUND
Requested Agent Class Constructor is not found.
|
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.
|
Constructor and Description |
---|
SAAgentV2(java.lang.String name,
android.content.Context context)
Creates an
SAAgentV2 instance with the specified name. |
SAAgentV2(java.lang.String name,
android.content.Context context,
java.lang.Class<? extends SASocket> socketClass)
|
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.
|
java.lang.String |
getServiceProfileId()
Gets the service profile ID that is declared in the Service Profile XML.
|
java.lang.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,
java.lang.String errorMessage,
int errorCode)
Called when an
SAAgentV2 error occurs in Samsung Accessory Service Framework. |
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 |
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 |
rejectServiceConnectionRequest(SAPeerAgent peerAgent)
Rejects a Service Connection request from the remote Accessory Peer Agent.
|
void |
releaseAgent()
|
static void |
requestAgent(android.content.Context context,
java.lang.String agentImplClass,
SAAgentV2.RequestAgentCallback callback)
|
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)
,
Constant Field Valuespublic static final int PEER_AGENT_AVAILABLE
Constant Value: 1 (0x00000001)
onPeerAgentsUpdated(SAPeerAgent[], int)
,
Constant Field Valuespublic static final int PEER_AGENT_UNAVAILABLE
Constant Value: 2 (0x00000002)
onPeerAgentsUpdated(SAPeerAgent[], int)
,
Constant Field Valuespublic static final int FINDPEER_DEVICE_NOT_CONNECTED
Constant Value: 1793 (0x00000701)
onFindPeerAgentsResponse(SAPeerAgent[], int)
,
Constant Field Valuespublic static final int FINDPEER_SERVICE_NOT_FOUND
Constant Value: 1794 (0x00000702)
onFindPeerAgentsResponse(SAPeerAgent[], int)
,
Constant Field Valuespublic static final int FINDPEER_DUPLICATE_REQUEST
findPeerAgents()
is still in progress.
Constant Value: 3085 (0x00000C0D)
onFindPeerAgentsResponse(SAPeerAgent[], int)
,
Constant Field Valuespublic static final int CONNECTION_SUCCESS
Constant Value: 0 (0x00000000)
onServiceConnectionResponse(SAPeerAgent, SASocket, int)
,
Constant Field Valuespublic static final int ERROR_CONNECTION_INVALID_PARAM
Constant Value: 1025 (0x00000401)
onError(SAPeerAgent, String, int)
,
Constant Field Valuespublic static final int CONNECTION_FAILURE_DEVICE_UNREACHABLE
Constant Value: 1028 (0x00000404)
onServiceConnectionResponse(SAPeerAgent, SASocket, int)
,
Constant Field Valuespublic static final int CONNECTION_ALREADY_EXIST
Constant Value: 1029 (0x00000405)
onServiceConnectionResponse(SAPeerAgent, SASocket, int)
,
Constant Field Valuespublic static final int CONNECTION_FAILURE_PEERAGENT_NO_RESPONSE
Constant Value: 1030 (0x00000406)
onServiceConnectionResponse(SAPeerAgent, SASocket, int)
,
Constant Field Valuespublic static final int CONNECTION_FAILURE_PEERAGENT_REJECTED
Constant Value: 1031 (0x00000407)
onServiceConnectionResponse(SAPeerAgent, SASocket, int)
,
Constant Field Valuespublic static final int CONNECTION_FAILURE_INVALID_PEERAGENT
SAPeerAgent
input argument is null or invalid.
Constant Value: 1033 (0x00000409)
onServiceConnectionResponse(SAPeerAgent, SASocket, int)
,
Constant Field Valuespublic static final int CONNECTION_DUPLICATE_REQUEST
Constant Value: 1040 (0x00000410)
onServiceConnectionResponse(SAPeerAgent, SASocket, int)
,
Constant Field Valuespublic static final int CONNECTION_FAILURE_SERVICE_LIMIT_REACHED
Constant Value: 1037 (0x0000040D)
onServiceConnectionResponse(SAPeerAgent, SASocket, int)
,
Constant Field Valuespublic static final int CONNECTION_FAILURE_NETWORK
Constant Value: 1280 (0x00000500)
onServiceConnectionResponse(SAPeerAgent, SASocket, int)
,
Constant Field Valuespublic 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(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(SAPeerAgent, String, int)
,
Constant Field Valuespublic static final int ERROR_PERMISSION_DENIED
Constant Value: 2304 (0x00000900)
onError(SAPeerAgent, String, int)
,
Constant Field Valuespublic static final int ERROR_PERMISSION_FAILED
Constant Value: 2305 (0x00000901)
onError(SAPeerAgent, String, int)
,
Constant Field Valuespublic static final int ERROR_CLASS_NOT_FOUND
requestAgent(Context, String, RequestAgentCallback)
Constant Value: 2561 (0x0A01)
SAAgentV2.RequestAgentCallback.onError(int, String)
,
Constant Field Valuespublic static final int ERROR_CONSTRUCTOR_NOT_FOUND
requestAgent(Context, String, RequestAgentCallback)
has a constructor with Context argument.
Constant Value: 2562 (0x0A02)
SAAgentV2.RequestAgentCallback.onError(int, String)
,
Constant Field Valuespublic static final int ERROR_CONSTRUCTOR_EXCEPTION
requestAgent(Context, String, RequestAgentCallback)
.
Constant Value: 2563 (0x0A03)
SAAgentV2.RequestAgentCallback.onError(int, String)
,
Constant Field Valuespublic static final int ERROR_AGENT_REQUEST_IN_PROGRESS
releaseAgent()
is still in progress.
Call requestAgent(Context, String, RequestAgentCallback)
after sometime.
Constant Value: 2564 (0x0A04)
SAAgentV2.RequestAgentCallback.onError(int, String)
,
Constant Field Valuespublic static final java.lang.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 java.lang.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"
public SAAgentV2(java.lang.String name, android.content.Context context)
SAAgentV2
instance with the specified 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 SAAgentV2(String, Context, Class)
if it makes use of both Service Connection
and Message Service feature.
name
- The name for the derived subclass that extends SAAgentV2
base class.context
- App contextpublic SAAgentV2(java.lang.String name, android.content.Context context, java.lang.Class<? extends SASocket> socketClass)
public static void requestAgent(android.content.Context context, java.lang.String agentImplClass, SAAgentV2.RequestAgentCallback callback)
SAAgentV2
from the static HashMap saved in SAAgentV2
.
Note: All Service Provider and Service Consumer applications should call this method
to create or get SAAgentV2
instance.
context
- App contextagentImplClass
- The name of the application that implementation Class SAAgentV2
.callback
- The instance of SAAgentV2.RequestAgentCallback
.public void releaseAgent()
SAAgentV2
from the static HashMap saved in SAAgentV2
.
Note: All Service Provider and Service Consumer applications Should call this method
in onDestroy of Activity when SAAgentV2
is no longer needed.
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()
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 SAAgentV2
that represents the remote Accessory Peer Agent that requests a
Service Connection.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 SAAgentV2
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 SAAgentV2
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)
protected void onError(SAPeerAgent peerAgent, java.lang.String errorMessage, int errorCode)
SAAgentV2
error occurs in Samsung Accessory Service Framework.
Note: Implement error handling by overriding this method.
peerAgent
- The instance of SAAgentV2
that represents the remote Accessory Peer Agent.errorMessage
- The error messageerrorCode
- The error code corresponding to ERROR_FATAL
, ERROR_SDK_NOT_INITIALIZED
,
ERROR_PERMISSION_DENIED
, or ERROR_PERMISSION_FAILED
.protected final void findPeerAgents()
Application should listen for the result of finding Accessory Peer Agent using
onFindPeerAgentsResponse(SAPeerAgent[], int)
callback. If multiple matching Accessory Peer Agents are
found, the onFindPeerAgentsResponse(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 onFindPeerAgentsResponse(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 SAAgentV2
that represents the remote Accessory Peer Agent whom requests Service
Connection to.java.lang.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 SAAgentV2
that represents the remote Accessory Peer Agent whose incoming
Service Connection requests.java.lang.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 SAAgentV2
that represents the remote Accessory Peer Agent whose incoming
Service Connection requests.java.lang.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 SAAgentV2
represents the remote Accessory Peer Agent to be authenticated.java.lang.IllegalArgumentException
- Thrown if the peerAgent argument passed is null or invalid.public java.lang.String getServiceProfileId()
public java.lang.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.