Use new SdkController communication protocol for emulation ports
android/sdk-control-socket.* has replaced android/android-device.* as the back-bone
of communicating with SDK controller on the device. The major differences are:
- New communication protocol uses just one (async) socket connection to communicate
with the device (the old one used two sockets: one sync, and another - async).
- New communication protocol connects to one TCP port (1970 in this CL) for all emulation
ports. Channel multiplexing is done by using port names, and assigning a separate socket
for communication inside each separate port. The old protocol had separate TCP ports for
each emulation ports (1968 for sensors, and 1969 for multi-touch)
Change-Id: I779fcbdfba2f9b4c433a9d76a567975708b00469
diff --git a/android/sdk-controller-socket.h b/android/sdk-controller-socket.h
index 03b12f4..e58a4e2 100644
--- a/android/sdk-controller-socket.h
+++ b/android/sdk-controller-socket.h
@@ -18,6 +18,7 @@
#define ANDROID_SDKCONTROL_SOCKET_H_
#include "android/async-socket.h"
+#include "android/async-utils.h"
/*
* Contains declaration of an API that encapsulates communication protocol with
@@ -102,20 +103,29 @@
* interested in that particular descriptor.
*
* There are three types of data in the exchange protocol:
- * - A packet - the simplest type of data that doesn't require any replies.
+ * - A message - the simplest type of data that doesn't require any replies.
* - A query - A message that require a reply, and
* - A query reply - A message that delivers query reply.
*/
+/* Default TCP port to use for connection with SDK controller. */
+#define SDKCTL_DEFAULT_TCP_PORT 1970
+
/* Declares SDK controller socket descriptor. */
typedef struct SDKCtlSocket SDKCtlSocket;
-/* Declares SDK controller data packet descriptor. */
-typedef struct SDKCtlPacket SDKCtlPacket;
+/* Declares SDK controller message descriptor. */
+typedef struct SDKCtlMessage SDKCtlMessage;
/* Declares SDK controller query descriptor. */
typedef struct SDKCtlQuery SDKCtlQuery;
+/* Declares SDK controller direct packet descriptor.
+ * Direct packet (unlike message, or query packets) doesn't contain data buffer,
+ * but rather references message, or query data allocated by the client.
+ */
+typedef struct SDKCtlDirectPacket SDKCtlDirectPacket;
+
/* Defines client's callback set to monitor SDK controller socket connection.
*
* SDKCtlSocket will invoke this callback when connection to TCP port is
@@ -137,30 +147,52 @@
* Return:
* One of the AsyncIOAction values.
*/
-typedef AsyncIOAction (*on_sdkctl_connection_cb)(void* client_opaque,
- SDKCtlSocket* sdkctl,
- AsyncIOState status);
+typedef AsyncIOAction (*on_sdkctl_socket_connection_cb)(void* client_opaque,
+ SDKCtlSocket* sdkctl,
+ AsyncIOState status);
-/* Defines client's callback set to receive handshake reply from the SdkController
- * service running on the device.
+/* Enumerates port connection statuses passed to port connection callback.
+ */
+typedef enum SdkCtlPortStatus {
+ /* Service-side port has connected to the socket. */
+ SDKCTL_PORT_DISCONNECTED,
+ /* Service-side port has disconnected from the socket. */
+ SDKCTL_PORT_CONNECTED,
+ /* Service-side port has enabled emulation */
+ SDKCTL_PORT_ENABLED,
+ /* Service-side port has disabled emulation */
+ SDKCTL_PORT_DISABLED,
+ /* Handshake request has succeeded, and service-side port is connected. */
+ SDKCTL_HANDSHAKE_CONNECTED,
+ /* Handshake request has succeeded, but service-side port is not connected. */
+ SDKCTL_HANDSHAKE_NO_PORT,
+ /* Handshake request has failed due to port duplication. */
+ SDKCTL_HANDSHAKE_DUP,
+ /* Handshake request has failed on an unknown query. */
+ SDKCTL_HANDSHAKE_UNKNOWN_QUERY,
+ /* Handshake request has failed on an unknown response. */
+ SDKCTL_HANDSHAKE_UNKNOWN_RESPONSE,
+} SdkCtlPortStatus;
+
+/* Defines client's callback set to receive port connection status.
*
- * Successful handshake means that connection between the client and SDK
- * controller service has been established.
+ * Port connection is different than socket connection, and indicates whether
+ * or not a service-side port that provides requested emulation functionality is
+ * hooked up with the connected socket. For instance, multi-touch port may be
+ * inactive at the time when socket is connected. So, there is a successful
+ * socket connection, but there is no service at the device end that provides
+ * multi-touch functionality. So, for multi-touch example, this callback will be
+ * invoked when multi-touch port at the device end becomes active, and hooks up
+ * with the socket that was connected before.
*
* Param:
* client_opaque - An opaque pointer associated with the client.
* sdkctl - Initialized SDKCtlSocket instance.
- * handshake - Handshake message received from the SDK controller service.
- * handshake_size - Size of the fandshake message received from the SDK
- * controller service.
- * status - Handshake status. Note that handshake, and handshake_size are valid
- * only if this parameter is set to ASIO_STATE_SUCCEEDED.
+ * status - Port connection status.
*/
-typedef void (*on_sdkctl_handshake_cb)(void* client_opaque,
- SDKCtlSocket* sdkctl,
- void* handshake,
- uint32_t handshake_size,
- AsyncIOState status);
+typedef void (*on_sdkctl_port_connection_cb)(void* client_opaque,
+ SDKCtlSocket* sdkctl,
+ SdkCtlPortStatus status);
/* Defines a message notification callback.
* Param:
@@ -176,7 +208,7 @@
*/
typedef void (*on_sdkctl_message_cb)(void* client_opaque,
SDKCtlSocket* sdkctl,
- SDKCtlPacket* message,
+ SDKCtlMessage* message,
int msg_type,
void* msg_data,
int msg_size);
@@ -203,27 +235,114 @@
SDKCtlQuery* query,
AsyncIOState status);
+/* Defines direct packet completion callback.
+ * Param:
+ * opaque - An opaque pointer associated with the direct packet by the client.
+ * packet - Packet descriptor. Note that packet descriptor will be released
+ * upon exit from this callback (thus, could be freed). If the client is
+ * interested in working with that packet after the callback returns, it
+ * should reference the packet descriptor in this callback.
+ * status - Packet status. Can be one of these:
+ * - ASIO_STATE_SUCCEEDED : Packet has been successfully sent.
+ * - ASIO_STATE_FAILED : Packet has failed on an I/O.
+ * - ASIO_STATE_CANCELLED : Packet has been cancelled due to socket
+ * disconnection.
+ * Return:
+ * One of the AsyncIOAction values.
+ */
+typedef AsyncIOAction (*on_sdkctl_direct_cb)(void* opaque,
+ SDKCtlDirectPacket* packet,
+ AsyncIOState status);
+
/********************************************************************************
- * SDKCtlPacket API
+ * SDKCtlDirectPacket API
********************************************************************************/
-/* References SDKCtlPacket object.
+/* Creates new SDKCtlDirectPacket descriptor.
* Param:
- * packet - Initialized SDKCtlPacket instance.
+ * sdkctl - Initialized SDKCtlSocket instance to create a direct packet for.
+ * Return:
+ * Referenced SDKCtlDirectPacket instance.
+ */
+extern SDKCtlDirectPacket* sdkctl_direct_packet_new(SDKCtlSocket* sdkctl);
+
+/* References SDKCtlDirectPacket object.
+ * Param:
+ * packet - Initialized SDKCtlDirectPacket instance.
* Return:
* Number of outstanding references to the object.
*/
-extern int sdkctl_packet_reference(SDKCtlPacket* packet);
+extern int sdkctl_direct_packet_reference(SDKCtlDirectPacket* packet);
-/* Releases SDKCtlPacket object.
+/* Releases SDKCtlDirectPacket object.
* Note that upon exiting from this routine the object might be destroyed, even
* if this routine returns value other than zero.
* Param:
- * packet - Initialized SDKCtlPacket instance.
+ * packet - Initialized SDKCtlDirectPacket instance.
* Return:
* Number of outstanding references to the object.
*/
-extern int sdkctl_packet_release(SDKCtlPacket* packet);
+extern int sdkctl_direct_packet_release(SDKCtlDirectPacket* packet);
+
+/* Sends direct packet.
+ * Param:
+ * packet - Packet descriptor for the direct packet to send.
+ * data - Data to send with the packet. Must be fully initialized message, or
+ * query header.
+ * cb, cb_opaque - Callback to invoke on packet transmission events.
+ */
+extern void sdkctl_direct_packet_send(SDKCtlDirectPacket* packet,
+ void* data,
+ on_sdkctl_direct_cb cb,
+ void* cb_opaque);
+
+/********************************************************************************
+ * SDKCtlMessage API
+ ********************************************************************************/
+
+/* References SDKCtlMessage object.
+ * Param:
+ * msg - Initialized SDKCtlMessage instance.
+ * Return:
+ * Number of outstanding references to the object.
+ */
+extern int sdkctl_message_reference(SDKCtlMessage* msg);
+
+/* Releases SDKCtlMessage object.
+ * Note that upon exiting from this routine the object might be destroyed, even
+ * if this routine returns value other than zero.
+ * Param:
+ * msg - Initialized SDKCtlMessage instance.
+ * Return:
+ * Number of outstanding references to the object.
+ */
+extern int sdkctl_message_release(SDKCtlMessage* msg);
+
+/* Builds and sends a message to the device.
+ * Param:
+ * sdkctl - SDKCtlSocket instance for the message.
+ * msg_type - Defines message type.
+ * data - Message data. Can be NULL if there is no data associated with the
+ * message.
+ * size - Byte size of the data buffer.
+ * Return:
+ * Referenced SDKCtlQuery descriptor.
+ */
+extern SDKCtlMessage* sdkctl_message_send(SDKCtlSocket* sdkctl,
+ int msg_type,
+ const void* data,
+ uint32_t size);
+
+/* Gets message header size */
+extern int sdkctl_message_get_header_size(void);
+
+/* Initializes message header.
+ * Param:
+ * msg - Beginning of the message packet.
+ * msg_type - Message type.
+ * msg_size - Message data size.
+ */
+extern void sdkctl_init_message_header(void* msg, int msg_type, int msg_size);
/********************************************************************************
* SDKCtlQuery API
@@ -349,6 +468,14 @@
*/
extern void* sdkctl_query_get_buffer_in(SDKCtlQuery* query);
+/* Gets address of query's output data buffer (response data).
+ * Param:
+ * query - Query to get data buffer for.
+ * Return:
+ * Address of query's output data buffer.
+ */
+extern void* sdkctl_query_get_buffer_out(SDKCtlQuery* query);
+
/********************************************************************************
* SDKCtlSocket API
********************************************************************************/
@@ -359,8 +486,8 @@
* attempts after disconnection, or on connection failures.
* service_name - Name of the SdkController service for this socket (such as
* 'sensors', 'milti-touch', etc.)
- * on_connection - A callback to invoke on socket connection events.
- * on_handshake - A callback to invoke on handshake events.
+ * on_socket_connection - A callback to invoke on socket connection events.
+ * on_port_connection - A callback to invoke on port connection events.
* on_message - A callback to invoke when a message is received from the SDK
* controller.
* opaque - An opaque pointer to associate with the socket.
@@ -369,8 +496,8 @@
*/
extern SDKCtlSocket* sdkctl_socket_new(int reconnect_to,
const char* service_name,
- on_sdkctl_connection_cb on_connection,
- on_sdkctl_handshake_cb on_handshake,
+ on_sdkctl_socket_connection_cb on_socket_connection,
+ on_sdkctl_port_connection_cb on_port_connection,
on_sdkctl_message_cb on_message,
void* opaque);
@@ -437,4 +564,36 @@
*/
extern void sdkctl_socket_disconnect(SDKCtlSocket* sdkctl);
+/* Checks if SDK controller socket is connected.
+ * Param:
+ * sdkctl - Initialized SDKCtlSocket instance.
+ * Return:
+ * Boolean: 1 if socket is connected, 0 if socket is not connected.
+ */
+extern int sdkctl_socket_is_connected(SDKCtlSocket* sdkctl);
+
+/* Checks if SDK controller port is ready for emulation.
+ * Param:
+ * sdkctl - Initialized SDKCtlSocket instance.
+ * Return:
+ * Boolean: 1 if port is ready, 0 if port is not ready.
+ */
+extern int sdkctl_socket_is_port_ready(SDKCtlSocket* sdkctl);
+
+/* Gets status of the SDK controller port for this socket.
+ * Param:
+ * sdkctl - Initialized SDKCtlSocket instance.
+ * Return:
+ * Status of the SDK controller port for this socket.
+ */
+extern SdkCtlPortStatus sdkctl_socket_get_port_status(SDKCtlSocket* sdkctl);
+
+/* Checks if handshake was successful.
+ * Param:
+ * sdkctl - Initialized SDKCtlSocket instance.
+ * Return:
+ * Boolean: 1 if handshake was successful, 0 if handshake was not successful.
+ */
+extern int sdkctl_socket_is_handshake_ok(SDKCtlSocket* sdkctl);
+
#endif /* ANDROID_SDKCONTROL_SOCKET_H_ */