Overview Package Class Tree Deprecated Index Help
com.samsung.android.sdk.accessory

Class SAAgent

  • java.lang.Object
    • android.content.Context
      • android.content.ContextWrapper
        • android.app.Service
          • com.samsung.android.sdk.accessory.SAAgent
  • All Implemented Interfaces:
    android.content.ComponentCallbacks, android.content.ComponentCallbacks2

    public abstract class SAAgent
extends android.app.Service
    SAAgent 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 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.

    • Field Detail

      • 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.0.19
        See Also:
        onPeerAgentsUpdated(SAPeerAgent[], 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.0.19
        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.1.8
        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.1.8
        See Also:
        onError(SAPeerAgent, String, int), 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.3.2
        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.3.2
        See Also:
        Constant Field Values

    • Constructor Detail

      • SAAgent

        protected SAAgent(java.lang.String name,
                  java.lang.Class<? extends SASocket> socketClass)
        Creates an SAAgent 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 SAAgent base class.
        socketClass - The subclass that extends SASocket base class, which represents a Service Connection between a Service Provider and a Service Consumer.
        Since:
        2.0.19

      • SAAgent

        protected SAAgent(java.lang.String name)
        Creates an SAAgent 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 SAAgent(String, Class) if it makes use of both Service Connection and Message Service feature.

        Parameters:
        name - The name for the derived subclass that extends SAAgent base class.
        Since:
        2.5.0

    • Method Detail

      • 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.3.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.3.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 SAAgent that represents the remote Accessory Peer Agent that requests a Service Connection.
        Since:
        2.0.19

      • 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 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.
        Since:
        2.1.8
        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 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.
        Since:
        2.0.19
        See Also:
        authenticatePeerAgent(SAPeerAgent)

      • onError

        protected void onError(SAPeerAgent peerAgent,
                       java.lang.String errorMessage,
                       int errorCode)
        Called when an SAAgent error occurs in Samsung Accessory Service Framework.

        Note: Implement error handling by overriding this method.

        Parameters:
        peerAgent - The instance of SAAgent that represents the remote Accessory Peer Agent.
        errorMessage - The error message
        errorCode - The error code corresponding to ERROR_* value.
        Since:
        2.1.8

      • 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 SAAgent 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.0.19

      • 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 SAAgent 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.0.19

      • 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.4.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.4.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.4.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.4.0