overview package class tree deprecated index help com.samsung.android.sdk.accessory class saagentv2 java.lang.object com.samsung.android.sdk.accessory.saagentv2 public abstract class saagentv2 extends java.lang.object saagentv2 provides the main interface between service provider and service consumer applications and samsung accessory service framework. developer guides 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. nested class summary nested classes modifier and type class and description static interface saagentv2.requestagentcallback callback interface for requestagent(context, string, requestagentcallback) to receive saagentv2 instance. field summary fields 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 summary constructors 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) creates an saagentv2 instance with the specified name and the derived subclass of sasocket. method summary all methods static methods instance methods concrete methods 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() release an instance of saagentv2 from the static hashmap saved in saagentv2. static void requestagent(android.content.context context, java.lang.string agentimplclass, saagentv2.requestagentcallback callback) request an instance of saagentv2 from the static hashmap saved in saagentv2. protected void requestserviceconnection(sapeeragent peeragent) requests a service connection with a remote accessory peer agent. field detail peer_agent_found public static final int peer_agent_found accessory peer agents have been found. constant value: 0 (0x00000000) since: 2.6.0 see also: onfindpeeragentsresponse(sapeeragent[], int), constant field values peer_agent_available public static final int peer_agent_available accessory peer agents have been available on a remote accessory device. constant value: 1 (0x00000001) since: 2.6.0 see also: onpeeragentsupdated(sapeeragent[], int), constant field values peer_agent_unavailable public static final int peer_agent_unavailable accessory peer agents have been unavailable on a remote accessory device. for example, the application package containing the accessory peer agent was uninstalled on the remote accessory device. constant value: 2 (0x00000002) since: 2.6.0 see also: onpeeragentsupdated(sapeeragent[], int), constant field values findpeer_device_not_connected public static final int findpeer_device_not_connected accessory devices are not connected. constant value: 1793 (0x00000701) since: 2.6.0 see also: onfindpeeragentsresponse(sapeeragent[], int), constant field values findpeer_service_not_found public static final int findpeer_service_not_found no matching accessory peer agents exist on connected accessory devices. constant value: 1794 (0x00000702) since: 2.6.0 see also: onfindpeeragentsresponse(sapeeragent[], int), constant field values findpeer_duplicate_request public static final int findpeer_duplicate_request another request to find an accessory peer agent calling findpeeragents() is still in progress. constant value: 3085 (0x00000c0d) since: 2.6.0 see also: onfindpeeragentsresponse(sapeeragent[], int), constant field values connection_success public static final int connection_success service connection has been established successfully. constant value: 0 (0x00000000) since: 2.6.0 see also: onserviceconnectionresponse(sapeeragent, sasocket, int), constant field values error_connection_invalid_param public static final int error_connection_invalid_param data kept by samsung accessory service framework was lost and cannot be recovered from this error in runtime. user may need to reboot the device. constant value: 1025 (0x00000401) since: 2.6.0 see also: onerror(sapeeragent, string, int), constant field values connection_failure_device_unreachable public static final int connection_failure_device_unreachable service connection establishment failed as the remote accessory peer agent is unreachable. constant value: 1028 (0x00000404) since: 2.6.0 see also: onserviceconnectionresponse(sapeeragent, sasocket, int), constant field values connection_already_exist public static final int connection_already_exist service connection establishment failed as another service connection request with the same remote accessory peer agent has been already established. constant value: 1029 (0x00000405) since: 2.6.0 see also: onserviceconnectionresponse(sapeeragent, sasocket, int), constant field values connection_failure_peeragent_no_response public static final int connection_failure_peeragent_no_response service connection establishment failed as the remote accessory peer agent does not give any response. constant value: 1030 (0x00000406) since: 2.6.0 see also: onserviceconnectionresponse(sapeeragent, sasocket, int), constant field values connection_failure_peeragent_rejected public static final int connection_failure_peeragent_rejected service connection establishment failed as the remote accessory peer agent rejected the request. constant value: 1031 (0x00000407) since: 2.6.0 see also: onserviceconnectionresponse(sapeeragent, sasocket, int), constant field values connection_failure_invalid_peeragent public static final int connection_failure_invalid_peeragent service connection establishment failed as the sapeeragent input argument is null or invalid. constant value: 1033 (0x00000409) since: 2.6.0 see also: onserviceconnectionresponse(sapeeragent, sasocket, int), constant field values connection_duplicate_request public static final int connection_duplicate_request service connection establishment failed as another attempt with same remote accessory peer agent is still in progress. constant value: 1040 (0x00000410) since: 2.6.0 see also: onserviceconnectionresponse(sapeeragent, sasocket, int), constant field values connection_failure_service_limit_reached public static final int connection_failure_service_limit_reached service connection establishment failed as the service limit set by the accessory peer agent has been reached. constant value: 1037 (0x0000040d) since: 2.6.0 see also: onserviceconnectionresponse(sapeeragent, sasocket, int), constant field values connection_failure_network public static final int connection_failure_network service connection establishment failed due to network errors. constant value: 1280 (0x00000500) since: 2.6.0 see also: onserviceconnectionresponse(sapeeragent, sasocket, int), constant field values authentication_success public static final int authentication_success authentication request succeeded. constant value: 0 (0x00000000) since: 2.6.0 see also: onauthenticationresponse(sapeeragent, saauthenticationtoken, int), constant field values authentication_failure_token_not_generated public static final int authentication_failure_token_not_generated the remote accessory peer agent's authentication token is not generated. constant value: 1545 (0x00000609) since: 2.6.0 see also: onauthenticationresponse(sapeeragent, saauthenticationtoken, int), constant field values authentication_failure_peer_agent_not_supported public static final int authentication_failure_peer_agent_not_supported the remote accessory peer agent does not support authentication. constant value: 1546 (0x00000610) since: 2.6.0 see also: onauthenticationresponse(sapeeragent, saauthenticationtoken, int), constant field values error_fatal public static final int error_fatal fatal error occurred such as binding failure or if the samsung accessory service framework has stopped. constant value: 2048 (0x00000800) since: 2.6.0 see also: onerror(sapeeragent, string, int), constant field values error_sdk_not_initialized public static final int error_sdk_not_initialized samsung accessory sdk is not initialized. all service provider and service consumer applications are expected to call sa.initialize(android.content.context) to initialize the samsung accessory sdk before using it. constant value: 2049 (0x00000801) since: 2.6.0 see also: onerror(sapeeragent, string, int), constant field values error_permission_denied public static final int error_permission_denied binding to samsung accessory service failed due to permission issue. it's advised to check the required permission in the application manifest file. constant value: 2304 (0x00000900) since: 2.6.0 see also: onerror(sapeeragent, string, int), constant field values error_permission_failed public static final int error_permission_failed binding to samsung accessory service failed due to permission mismatch. it's advised to reinstall the application as the samsung accessory service framework is installed after the application installation. constant value: 2305 (0x00000901) since: 2.6.0 see also: onerror(sapeeragent, string, int), constant field values error_class_not_found public static final int error_class_not_found requested agent class is not found. verify the class name passed in requestagent(context, string, requestagentcallback) constant value: 2561 (0x0a01) since: 2.6.0 see also: saagentv2.requestagentcallback.onerror(int, string), constant field values error_constructor_not_found public static final int error_constructor_not_found requested agent class constructor is not found. verify the agent class which name is passed in requestagent(context, string, requestagentcallback) has a constructor with context argument. constant value: 2562 (0x0a02) since: 2.6.0 see also: saagentv2.requestagentcallback.onerror(int, string), constant field values error_constructor_exception public static final int error_constructor_exception requested agent class constructor threw an exception. check the constructor code of the class which name is passed in requestagent(context, string, requestagentcallback). constant value: 2563 (0x0a03) since: 2.6.0 see also: saagentv2.requestagentcallback.onerror(int, string), constant field values error_agent_request_in_progress public static final int error_agent_request_in_progress requested agent class is being released. release agent releaseagent() is still in progress. call requestagent(context, string, requestagentcallback) after sometime. constant value: 2564 (0x0a04) since: 2.6.0 see also: saagentv2.requestagentcallback.onerror(int, string), constant field values action_service_connection_requested public static final java.lang.string action_service_connection_requested broadcast action: indicates that an incoming service connection request from remote accessory peer agent has been received. 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" since: 2.6.0 see also: constant field values action_registration_required public static final java.lang.string action_registration_required broadcast action: indicates that an installed peer agent has been required to register. 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" since: 2.6.0 see also: constant field values constructor detail saagentv2 public saagentv2(java.lang.string name, android.content.context context) creates an 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. parameters: name - the name for the derived subclass that extends saagentv2 base class. context - app context since: 2.6.0 saagentv2 public saagentv2(java.lang.string name, android.content.context context, java.lang.class<? extends sasocket> socketclass) creates an saagentv2 instance with the specified name and the derived subclass of 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. parameters: name - the name for the derived subclass that extends saagentv2 base class. context - app context socketclass - the subclass that extends sasocket base class, which represents a service connection between a service provider and a service consumer. since: 2.6.0 method detail requestagent public static void requestagent(android.content.context context, java.lang.string agentimplclass, saagentv2.requestagentcallback callback) request an instance of 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. parameters: context - app context agentimplclass - the name of the application that implementation class saagentv2. callback - the instance of saagentv2.requestagentcallback. since: 2.6.0 releaseagent public void releaseagent() release an instance of 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. since: 2.6.0 onfindpeeragentsresponse protected void onfindpeeragentsresponse(sapeeragent[] peeragents, int result) called when the discovery for matching accessory peer agents is completed. if matching accessory peer agents are found (on the same or multiple remote accessory devices), this callback occurs with a list of peer agents. 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. parameters: 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. since: 2.6.0 see also: findpeeragents() onpeeragentsupdated protected void onpeeragentsupdated(sapeeragent[] peeragents, int result) called when the status of remote accessory peer agent on a connected remote accessory devices changes. this callback is invoked only if you have previously initiated a service discovery request by calling 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. parameters: 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. since: 2.6.0 onserviceconnectionrequested protected void onserviceconnectionrequested(sapeeragent peeragent) called when a remote accessory peer agent requests a service connection. 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. parameters: peeragent - the instance of saagentv2 that represents the remote accessory peer agent that requests a service connection. since: 2.6.0 onserviceconnectionresponse protected void onserviceconnectionresponse(sapeeragent peeragent, sasocket socket, int result) called when a service connection to a remote accessory peer agent is established or failed. this is typically a result of 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). parameters: 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. since: 2.6.0 see also: requestserviceconnection(sapeeragent) onauthenticationresponse protected void onauthenticationresponse(sapeeragent peeragent, saauthenticationtoken authtoken, int code) called when the accessory peer agent authentication is completed. 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. parameters: 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. since: 2.6.0 see also: authenticatepeeragent(sapeeragent) onerror protected void onerror(sapeeragent peeragent, java.lang.string errormessage, int errorcode) called when an saagentv2 error occurs in samsung accessory service framework. note: implement error handling by overriding this method. parameters: peeragent - the instance of saagentv2 that represents the remote accessory peer agent. errormessage - the error message errorcode - the error code corresponding to error_fatal, error_sdk_not_initialized, error_permission_denied, or error_permission_failed. since: 2.6.0 findpeeragents protected final void findpeeragents() finds matching accessory peer agents. 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. since: 2.6.0 requestserviceconnection protected final void requestserviceconnection(sapeeragent peeragent) requests a service connection with a remote accessory peer agent. 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. parameters: peeragent - the instance of saagentv2 that represents the remote accessory peer agent whom requests service connection to. throws: java.lang.illegalargumentexception - thrown if peeragent argument passed is null or invalid. since: 2.6.0 acceptserviceconnectionrequest protected void acceptserviceconnectionrequest(sapeeragent peeragent) accepts a service connection request from the remote accessory peer agent. 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. parameters: peeragent - the instance of saagentv2 that represents the remote accessory peer agent whose incoming service connection requests. throws: java.lang.illegalargumentexception - thrown if the peeragent argument passed is null or invalid. since: 2.6.0 rejectserviceconnectionrequest protected void rejectserviceconnectionrequest(sapeeragent peeragent) rejects a service connection request from the remote accessory peer agent. 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. parameters: peeragent - the instance of saagentv2 that represents the remote accessory peer agent whose incoming service connection requests. throws: java.lang.illegalargumentexception - thrown if the peeragent argument is null or invalid. since: 2.6.0 authenticatepeeragent protected void authenticatepeeragent(sapeeragent peeragent) authenticates an accessory peer agent. 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. parameters: peeragent - the instance of saagentv2 represents the remote accessory peer agent to be authenticated. throws: java.lang.illegalargumentexception - thrown if the peeragent argument passed is null or invalid. since: 2.6.0 getserviceprofileid public java.lang.string getserviceprofileid() gets the service profile id that is declared in the service profile xml. returns: service profile id. null if the xml-parsing logic has a problem. since: 2.6.0 getserviceprofilename public java.lang.string getserviceprofilename() gets the service profile name that is declared in the service profile xml. returns: service profile name. null if the xml-parsing logic has a problem. since: 2.6.0 getservicechannelsize public int getservicechannelsize() gets the size of the service channel list that is declared in the service profile xml. 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. returns: the size of the service channel list. -1 if the xml-parsing logic has a problem and return 0 if there is no channel in the service profile xml. since: 2.6.0 getservicechannelid public int getservicechannelid(int index) gets the service channel id at the specific index of the list that is declared in the service profile xml. 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[]). parameters: index - the index of channel id in the service channel list. it starts from index 0 returns: service channel id at the given index. -1 if the xml-parsing logic has a problem. since: 2.6.0