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.

    • 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)

      • 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

      • 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