android/android-device.h - platform/external/qemu - Git at Google

 /*
  * Copyright (C) 2011 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 #ifndef ANDROID_ANDROID_DEVICE_H_
 #define ANDROID_ANDROID_DEVICE_H_

 /*
  * Encapsulates an exchange protocol between the emulator, and an Android device
  * that is connected to the host via USB. The communication is established over
  * a TCP port forwarding, enabled by ADB (always use 'adb -d forward ...' variant
  * of this command, so ADB will know to enable port forwarding on the connected
  * device, and not on the emulator's guest system).
  *
  * Exchange protocol contains two channel:
  *
  * - Query channel.
  * - Event channel.
  *
  * Both channels are implemented on top of TCP sockets that are connected to the
  * same port.
  *
  * I QUERY CHANNEL.
  * Query channel is intended to send queries to and receive responses from the
  * connected device. It is implemented on top of iolooper_xxx API (see iolooper.h)
  * because it must work outside of the main event loop. This is required to enable
  * proper initialization of components (such as sensors) that must be set up
  * before emulator enters the main loop.
  *
  * II EVENT CHANNEL.
  * Event channel is intended to listen on events sent from the device, and
  * asynchronously report them back to the client of this API by invoking an event
  * callback that was registered by the client. Event channel is implemented on
  * top of asyncXxx API (see android/async-utils.*). Note that using of asyncXxx
  * API limits the use of event channel to the time after the emulator has entered
  * its main event loop. The only exception is if event channel is connected from
  * android_device_connect_sync API, in which case iolooper_xxx API is used to
  * establish the connection. However, even in this case listening for events will
  * not be available until after the emulator enters its event loop, since event
  * listening always uses asyncXxx API.
  *
  * III. ESTABLISHING CONNECTION.
  * ADB port forwarding requires that the server socket is to be run on the device,
  * while emulator must use a client socket for communication. Thus, it's the
  * emulator that initiates the connection.
  *
  * There are two ways how emulator can initiate the connection:
  *
  * - Synchronous connection.
  * - Asynchronous connection.
  *
  * III.I SYNCHROUNOUS CONNECTION.
  * Synchronous connection is initiated via android_device_connect_sync API, and
  * completes synchronously.
  *
  * This API should be used when connection with the device is required at the time
  * of the call. For instance, when initializing sensor emulation, connection with
  * the device is required to properly set up the emulator before the guest system
  * starts, and before emulator enters its main event loop.
  *
  * III.II ASYNCHRONOUS CONNECTION.
  * Asynchronous connection is initiated via android_device_connect_async API. The
  * main difference with the synchronous connection is that this API will not fail
  * if connection is not immediately available. If connection is not available at
  * the time of the call, the API will schedule a retry (based on a timer), and
  * will continue reprying untill connection becomes available, or until an error
  * occurs that prevent further retries.
  *
  * This API should be used when ... Well, whenever appropriate. For instance,
  * sensor emulation will use this API to restore lost connection with the device.
  *
  * NOTE: Asynchronous connection will complete no sooner than the emulator enters
  * its main loop.
  *
  * IV EXCHANGE PROTOCOL.
  * Obviously, there must be some application running on the device, that implements
  * a socket server listening on the forwarded TCP port, and accepting the clients.
  *
  * IV.I Query vs. event channel.
  * The exchange protocol assumes, that when a channel is connected, it will
  * identify itself by sending a string containing channel type. Only after such
  * identification has been made the channel becomes available for use.
  *
  * IV.II Message format.
  * All data that is transferred in both directions over both channels are zero-
  * terminated strings.
  */

 #include "qemu-common.h"
 #include "android/async-utils.h"
 #include "android/utils/debug.h"

 /* TCP port reserved for sensor emulation. */
 #define AD_SENSOR_PORT  1968

 /* Definis infinite timeout. */
 #define AD_INFINITE_WAIT    -1

 /* Enumerates results of asynchronous data transfer.
  */
 typedef enum ATResult {
     /* Data transfer has been completed. */
     ATR_SUCCESS,
     /* Socket got disconnected while data transfer has been in progress. */
     ATR_DISCONNECT,
     /* An I/O error has occured. 'errno' contains error value. */
     ATR_IO_ERROR,
 } ATResult;

 /* Android device descriptor. */
 typedef struct AndroidDevice AndroidDevice;

 /********************************************************************************
  *                       Callback declarations
  *******************************************************************************/

 /* Callback routine that is invoked when android device is connected, or failed
  * to connect. As discussed above, this callback is called when both, query and
  * event channels have been connected. This callback is used only for asynchronous
  * connections.
  * Param:
  *  opaque - Opaque pointer that was passed to android_device_init API.
  *  ad - Androd device descriptor for the connection.
  *  failure - Zero indicates that connection with the device has been successfuly
  *      established. Non-zero vaule passed in this parameter indicates a failure,
  *      and contains 'errno'-reason for failure.
  */
 typedef void (*device_connected_cb)(void* opaque, AndroidDevice* ad, int failure);

 /* Callback routine that is invoked on an event received in the event channel.
  * NOTE: It's important to check 'errno' in this callback. If 'errno' is set to
  * ENOMEM, this signals that buffer passed to android_device_listen was too small
  * to contain the entire event message.
  * Param:
  *  opaque - Opaque pointer that was passed to android_device_init API.
  *  ad - Androd device descriptor for the connection.
  *  msg - Event message (a zero-terminated string) received from the device.
  *  msgsize - Event message size (including zero-terminator).
  */
 typedef void (*event_cb)(void* opaque, AndroidDevice* ad, char* msg, int msgsize);

 /* Callback routine that is invoked when an I/O failure occurs on a channel.
  * Note that this callback will not be invoked on connection failures.
  * Param:
  *  opaque - Opaque pointer that was passed to android_device_init API.
  *  ad - Android device instance
  *  failure - Contains 'errno' indicating the reason for failure.
  */
 typedef void (*io_failure_cb)(void* opaque, AndroidDevice* ad, int failure);

 /* Callback routine that is invoked when an asynchronous data send has been
  * completed.
  * Param:
  *  opaque - An opaque pointer associated with the data.
  *  res - Result of data transfer.
  *  data, size - Transferred data buffer.
  *  sent - Number of sent bytes.
  */
 typedef void (*async_send_cb)(void* opaque,
                               ATResult res,
                               void* data,
                               int size,
                               int sent);

 /********************************************************************************
  *                       Android Device API.
  *******************************************************************************/

 /* Initializes android device descriptor.
  * Param:
  *  opaque - An opaque pointer to associate with the descriptor. This pointer
  *      will be passed to all callbacks (see above) that were invoked by the
  *      initializing android device instance.
  *  port - TCP port to use for connection.
  *  on_io_failure - Callback to invoke when an I/O failure occurs on a channel
  *      used by the initializing android device instance. Can be NULL.
  * Return:
  *  Initialized android device descriptor on success, or NULL on failure.
  */
 extern AndroidDevice* android_device_init(void* opaque,
                                           int port,
                                           io_failure_cb on_io_failure);

 /* Disconnects and destroys android device descriptor.
  * Param:
  *  ad - Android device descriptor, returned from android_device_init API.
  *      Note that memory allocated for this descriptor will be freed in this
  *      routine.
  */
 extern void android_device_destroy(AndroidDevice* ad);

 /* Synchronously connects to the device. See notes above for more details.
  * Param:
  *  ad - Android device descriptor, returned from android_device_init API.
  *  to - Milliseconds to wait for connection to be established.
  * Return:
  *  Zero on success, or non-zero value on failure with 'errno' properly set.
  */
 extern int android_device_connect_sync(AndroidDevice* ad, int to);

 /* Asynchronously connects to the device. See notes above for more details.
  * Param:
  *  ad - Android device descriptor, returned from android_device_init API.
  *  on_connected - Callback to invoke when connection is completed (i,e, both,
  *      event, and query channels have been connected). This parameter can be
  *      NULL. Note that connection errors will be also reported through this
  *      callback. Also note that this callback will be invoked even if this
  *      routine returns with a failure.
  * Return:
  *  Zero on success, or non-zero value on failure with 'errno' properly set.
  */
 extern int android_device_connect_async(AndroidDevice* ad,
                                         device_connected_cb on_connected);

 /* Disconnects from the android device.
  * Param:
  *  ad - Android device descriptor, returned from android_device_init API.
  */
 extern void android_device_disconnect(AndroidDevice* ad);

 /* Queries the device via query channel.
  * Param:
  *  ad - Android device descriptor, returned from android_device_init API.
  *  query - Zero-terminated query string.
  *  buff, buffsize - Buffer where to receive the response to the query.
  *  to - Milliseconds to wait for the entire query to complete.
  * Return:
  *  Zero on success, or non-zero value on failure with 'errno' properly set:
  *      - 0 Indicates that the server has failed the query.
  *      - Anything else indicates an I/O error.
  */
 extern int android_device_query(AndroidDevice* ad,
                                 const char* query,
                                 char* buff,
                                 size_t buffsize,
                                 int to);

 /* Starts a query that may require more than one buffer transfer.
  * This routine allows to initiate a query that may require more than one call to
  * send_data, or may have a format that differs from the usual (a zero-terminated
  * string). For instance, sending a BLOB data should use this routine to start a
  * a query, then use android_device_send_query_data to transfer the data, and
  * then call android_device_complete_query to obtain the response.
  * Param:
  *  ad - Android device descriptor, returned from android_device_init API.
  *  query - Zero-terminated query string.
  *  to - Milliseconds to wait for the entire query to complete.
  * Return:
  *  Zero on success, or non-zero value on failure with 'errno' properly set:
  *      - 0 Indicates that the server has failed the query.
  *      - Anything else indicates an I/O error.
  */
 extern int android_device_start_query(AndroidDevice* ad,
                                       const char* query,
                                       int to);

 /* Sends data block for a query started with android_device_start_query
  * Param:
  *  ad - Android device descriptor, returned from android_device_init API.
  *  data, size - Data to transfer.
  * Return:
  *  Number of bytes transferred on success, or -1 on failure with errno
  *  containing the reason for failure.
  */
 extern int android_device_send_query_data(AndroidDevice* ad,
                                           const void* data,
                                           int size);

 /* Completes a query started with android_device_start_query, and receives the
  * query response.
  * Param:
  *  ad - Android device descriptor, returned from android_device_init API.
  *  buff, buffsize - Buffer where to receive the response to the query.
  * Return:
  *  Zero on success, or non-zero value on failure with 'errno' properly set.
  */
 extern int android_device_complete_query(AndroidDevice* ad, char* buff, size_t buffsize);

 /* Start listening on the event channel.
  * Param:
  *  ad - Android device descriptor, returned from android_device_init API.
  *  buff, buffsize - Buffer where to receive the event message.
  *  on_event - Callback to invoke on event. Note that this callback will be
  *      invoked even if this routine returns with a failure.
  * Return:
  *  Zero on success, or non-zero value on failure with 'errno' properly set.
  */
 extern int android_device_listen(AndroidDevice* ad,
                                  char* buff,
                                  int buffsize,
                                  event_cb on_event);

 /* Asynchronously sends data to the android device.
  * Param:
  *  ad - Android device descriptor, returned from android_device_init API.
  *  data, size - Buffer containing data to send.
  *  free_on_close - A boolean flag indicating whether the data buffer should be
  *      freed upon data transfer completion.
  *  cb - Callback to invoke when data transfer is completed.
  *  opaque - An opaque pointer to pass to the transfer completion callback.
  */
 extern int android_device_send_async(AndroidDevice* ad,
                                      void* data,
                                      int size,
                                      int free_on_close,
                                      async_send_cb cb,
                                      void* opaque);

 #endif  /* ANDROID_ANDROID_DEVICE_H_ */
	/*
	* Copyright (C) 2011 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	#ifndef ANDROID_ANDROID_DEVICE_H_
	#define ANDROID_ANDROID_DEVICE_H_

	/*
	* Encapsulates an exchange protocol between the emulator, and an Android device
	* that is connected to the host via USB. The communication is established over
	* a TCP port forwarding, enabled by ADB (always use 'adb -d forward ...' variant
	* of this command, so ADB will know to enable port forwarding on the connected
	* device, and not on the emulator's guest system).
	*
	* Exchange protocol contains two channel:
	*
	* - Query channel.
	* - Event channel.
	*
	* Both channels are implemented on top of TCP sockets that are connected to the
	* same port.
	*
	* I QUERY CHANNEL.
	* Query channel is intended to send queries to and receive responses from the
	* connected device. It is implemented on top of iolooper_xxx API (see iolooper.h)
	* because it must work outside of the main event loop. This is required to enable
	* proper initialization of components (such as sensors) that must be set up
	* before emulator enters the main loop.
	*
	* II EVENT CHANNEL.
	* Event channel is intended to listen on events sent from the device, and
	* asynchronously report them back to the client of this API by invoking an event
	* callback that was registered by the client. Event channel is implemented on
	* top of asyncXxx API (see android/async-utils.*). Note that using of asyncXxx
	* API limits the use of event channel to the time after the emulator has entered
	* its main event loop. The only exception is if event channel is connected from
	* android_device_connect_sync API, in which case iolooper_xxx API is used to
	* establish the connection. However, even in this case listening for events will
	* not be available until after the emulator enters its event loop, since event
	* listening always uses asyncXxx API.
	*
	* III. ESTABLISHING CONNECTION.
	* ADB port forwarding requires that the server socket is to be run on the device,
	* while emulator must use a client socket for communication. Thus, it's the
	* emulator that initiates the connection.
	*
	* There are two ways how emulator can initiate the connection:
	*
	* - Synchronous connection.
	* - Asynchronous connection.
	*
	* III.I SYNCHROUNOUS CONNECTION.
	* Synchronous connection is initiated via android_device_connect_sync API, and
	* completes synchronously.
	*
	* This API should be used when connection with the device is required at the time
	* of the call. For instance, when initializing sensor emulation, connection with
	* the device is required to properly set up the emulator before the guest system
	* starts, and before emulator enters its main event loop.
	*
	* III.II ASYNCHRONOUS CONNECTION.
	* Asynchronous connection is initiated via android_device_connect_async API. The
	* main difference with the synchronous connection is that this API will not fail
	* if connection is not immediately available. If connection is not available at
	* the time of the call, the API will schedule a retry (based on a timer), and
	* will continue reprying untill connection becomes available, or until an error
	* occurs that prevent further retries.
	*
	* This API should be used when ... Well, whenever appropriate. For instance,
	* sensor emulation will use this API to restore lost connection with the device.
	*
	* NOTE: Asynchronous connection will complete no sooner than the emulator enters
	* its main loop.
	*
	* IV EXCHANGE PROTOCOL.
	* Obviously, there must be some application running on the device, that implements
	* a socket server listening on the forwarded TCP port, and accepting the clients.
	*
	* IV.I Query vs. event channel.
	* The exchange protocol assumes, that when a channel is connected, it will
	* identify itself by sending a string containing channel type. Only after such
	* identification has been made the channel becomes available for use.
	*
	* IV.II Message format.
	* All data that is transferred in both directions over both channels are zero-
	* terminated strings.
	*/

	#include "qemu-common.h"
	#include "android/async-utils.h"
	#include "android/utils/debug.h"

	/* TCP port reserved for sensor emulation. */
	#define AD_SENSOR_PORT 1968

	/* Definis infinite timeout. */
	#define AD_INFINITE_WAIT -1

	/* Enumerates results of asynchronous data transfer.
	*/
	typedef enum ATResult {
	/* Data transfer has been completed. */
	ATR_SUCCESS,
	/* Socket got disconnected while data transfer has been in progress. */
	ATR_DISCONNECT,
	/* An I/O error has occured. 'errno' contains error value. */
	ATR_IO_ERROR,
	} ATResult;

	/* Android device descriptor. */
	typedef struct AndroidDevice AndroidDevice;

	/********************************************************************************
	* Callback declarations
	*******************************************************************************/

	/* Callback routine that is invoked when android device is connected, or failed
	* to connect. As discussed above, this callback is called when both, query and
	* event channels have been connected. This callback is used only for asynchronous
	* connections.
	* Param:
	* opaque - Opaque pointer that was passed to android_device_init API.
	* ad - Androd device descriptor for the connection.
	* failure - Zero indicates that connection with the device has been successfuly
	* established. Non-zero vaule passed in this parameter indicates a failure,
	* and contains 'errno'-reason for failure.
	*/
	typedef void (device_connected_cb)(void opaque, AndroidDevice* ad, int failure);

	/* Callback routine that is invoked on an event received in the event channel.
	* NOTE: It's important to check 'errno' in this callback. If 'errno' is set to
	* ENOMEM, this signals that buffer passed to android_device_listen was too small
	* to contain the entire event message.
	* Param:
	* opaque - Opaque pointer that was passed to android_device_init API.
	* ad - Androd device descriptor for the connection.
	* msg - Event message (a zero-terminated string) received from the device.
	* msgsize - Event message size (including zero-terminator).
	*/
	typedef void (event_cb)(void opaque, AndroidDevice* ad, char* msg, int msgsize);

	/* Callback routine that is invoked when an I/O failure occurs on a channel.
	* Note that this callback will not be invoked on connection failures.
	* Param:
	* opaque - Opaque pointer that was passed to android_device_init API.
	* ad - Android device instance
	* failure - Contains 'errno' indicating the reason for failure.
	*/
	typedef void (io_failure_cb)(void opaque, AndroidDevice* ad, int failure);

	/* Callback routine that is invoked when an asynchronous data send has been
	* completed.
	* Param:
	* opaque - An opaque pointer associated with the data.
	* res - Result of data transfer.
	* data, size - Transferred data buffer.
	* sent - Number of sent bytes.
	*/
	typedef void (async_send_cb)(void opaque,
	ATResult res,
	void* data,
	int size,
	int sent);

	/********************************************************************************
	* Android Device API.
	*******************************************************************************/

	/* Initializes android device descriptor.
	* Param:
	* opaque - An opaque pointer to associate with the descriptor. This pointer
	* will be passed to all callbacks (see above) that were invoked by the
	* initializing android device instance.
	* port - TCP port to use for connection.
	* on_io_failure - Callback to invoke when an I/O failure occurs on a channel
	* used by the initializing android device instance. Can be NULL.
	* Return:
	* Initialized android device descriptor on success, or NULL on failure.
	*/
	extern AndroidDevice* android_device_init(void* opaque,
	int port,
	io_failure_cb on_io_failure);

	/* Disconnects and destroys android device descriptor.
	* Param:
	* ad - Android device descriptor, returned from android_device_init API.
	* Note that memory allocated for this descriptor will be freed in this
	* routine.
	*/
	extern void android_device_destroy(AndroidDevice* ad);

	/* Synchronously connects to the device. See notes above for more details.
	* Param:
	* ad - Android device descriptor, returned from android_device_init API.
	* to - Milliseconds to wait for connection to be established.
	* Return:
	* Zero on success, or non-zero value on failure with 'errno' properly set.
	*/
	extern int android_device_connect_sync(AndroidDevice* ad, int to);

	/* Asynchronously connects to the device. See notes above for more details.
	* Param:
	* ad - Android device descriptor, returned from android_device_init API.
	* on_connected - Callback to invoke when connection is completed (i,e, both,
	* event, and query channels have been connected). This parameter can be
	* NULL. Note that connection errors will be also reported through this
	* callback. Also note that this callback will be invoked even if this
	* routine returns with a failure.
	* Return:
	* Zero on success, or non-zero value on failure with 'errno' properly set.
	*/
	extern int android_device_connect_async(AndroidDevice* ad,
	device_connected_cb on_connected);

	/* Disconnects from the android device.
	* Param:
	* ad - Android device descriptor, returned from android_device_init API.
	*/
	extern void android_device_disconnect(AndroidDevice* ad);

	/* Queries the device via query channel.
	* Param:
	* ad - Android device descriptor, returned from android_device_init API.
	* query - Zero-terminated query string.
	* buff, buffsize - Buffer where to receive the response to the query.
	* to - Milliseconds to wait for the entire query to complete.
	* Return:
	* Zero on success, or non-zero value on failure with 'errno' properly set:
	* - 0 Indicates that the server has failed the query.
	* - Anything else indicates an I/O error.
	*/
	extern int android_device_query(AndroidDevice* ad,
	const char* query,
	char* buff,
	size_t buffsize,
	int to);

	/* Starts a query that may require more than one buffer transfer.
	* This routine allows to initiate a query that may require more than one call to
	* send_data, or may have a format that differs from the usual (a zero-terminated
	* string). For instance, sending a BLOB data should use this routine to start a
	* a query, then use android_device_send_query_data to transfer the data, and
	* then call android_device_complete_query to obtain the response.
	* Param:
	* ad - Android device descriptor, returned from android_device_init API.
	* query - Zero-terminated query string.
	* to - Milliseconds to wait for the entire query to complete.
	* Return:
	* Zero on success, or non-zero value on failure with 'errno' properly set:
	* - 0 Indicates that the server has failed the query.
	* - Anything else indicates an I/O error.
	*/
	extern int android_device_start_query(AndroidDevice* ad,
	const char* query,
	int to);

	/* Sends data block for a query started with android_device_start_query
	* Param:
	* ad - Android device descriptor, returned from android_device_init API.
	* data, size - Data to transfer.
	* Return:
	* Number of bytes transferred on success, or -1 on failure with errno
	* containing the reason for failure.
	*/
	extern int android_device_send_query_data(AndroidDevice* ad,
	const void* data,
	int size);

	/* Completes a query started with android_device_start_query, and receives the
	* query response.
	* Param:
	* ad - Android device descriptor, returned from android_device_init API.
	* buff, buffsize - Buffer where to receive the response to the query.
	* Return:
	* Zero on success, or non-zero value on failure with 'errno' properly set.
	*/
	extern int android_device_complete_query(AndroidDevice* ad, char* buff, size_t buffsize);

	/* Start listening on the event channel.
	* Param:
	* ad - Android device descriptor, returned from android_device_init API.
	* buff, buffsize - Buffer where to receive the event message.
	* on_event - Callback to invoke on event. Note that this callback will be
	* invoked even if this routine returns with a failure.
	* Return:
	* Zero on success, or non-zero value on failure with 'errno' properly set.
	*/
	extern int android_device_listen(AndroidDevice* ad,
	char* buff,
	int buffsize,
	event_cb on_event);

	/* Asynchronously sends data to the android device.
	* Param:
	* ad - Android device descriptor, returned from android_device_init API.
	* data, size - Buffer containing data to send.
	* free_on_close - A boolean flag indicating whether the data buffer should be
	* freed upon data transfer completion.
	* cb - Callback to invoke when data transfer is completed.
	* opaque - An opaque pointer to pass to the transfer completion callback.
	*/
	extern int android_device_send_async(AndroidDevice* ad,
	void* data,
	int size,
	int free_on_close,
	async_send_cb cb,
	void* opaque);

	#endif /* ANDROID_ANDROID_DEVICE_H_ */