1 /* 2 * Copyright (C) 2011 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef ANDROID_ANDROID_DEVICE_H_ 18 #define ANDROID_ANDROID_DEVICE_H_ 19 20 /* 21 * Encapsulates an exchange protocol between the emulator, and an Android device 22 * that is connected to the host via USB. The communication is established over 23 * a TCP port forwarding, enabled by ADB (always use 'adb -d forward ...' variant 24 * of this command, so ADB will know to enable port forwarding on the connected 25 * device, and not on the emulator's guest system). 26 * 27 * Exchange protocol contains two channel: 28 * 29 * - Query channel. 30 * - Event channel. 31 * 32 * Both channels are implemented on top of TCP sockets that are connected to the 33 * same port. 34 * 35 * I QUERY CHANNEL. 36 * Query channel is intended to send queries to and receive responses from the 37 * connected device. It is implemented on top of iolooper_xxx API (see iolooper.h) 38 * because it must work outside of the main event loop. This is required to enable 39 * proper initialization of components (such as sensors) that must be set up 40 * before emulator enters the main loop. 41 * 42 * II EVENT CHANNEL. 43 * Event channel is intended to listen on events sent from the device, and 44 * asynchronously report them back to the client of this API by invoking an event 45 * callback that was registered by the client. Event channel is implemented on 46 * top of asyncXxx API (see android/async-utils.*). Note that using of asyncXxx 47 * API limits the use of event channel to the time after the emulator has entered 48 * its main event loop. The only exception is if event channel is connected from 49 * android_device_connect_sync API, in which case iolooper_xxx API is used to 50 * establish the connection. However, even in this case listening for events will 51 * not be available until after the emulator enters its event loop, since event 52 * listening always uses asyncXxx API. 53 * 54 * III. ESTABLISHING CONNECTION. 55 * ADB port forwarding requires that the server socket is to be run on the device, 56 * while emulator must use a client socket for communication. Thus, it's the 57 * emulator that initiates the connection. 58 * 59 * There are two ways how emulator can initiate the connection: 60 * 61 * - Synchronous connection. 62 * - Asynchronous connection. 63 * 64 * III.I SYNCHROUNOUS CONNECTION. 65 * Synchronous connection is initiated via android_device_connect_sync API, and 66 * completes synchronously. 67 * 68 * This API should be used when connection with the device is required at the time 69 * of the call. For instance, when initializing sensor emulation, connection with 70 * the device is required to properly set up the emulator before the guest system 71 * starts, and before emulator enters its main event loop. 72 * 73 * III.II ASYNCHRONOUS CONNECTION. 74 * Asynchronous connection is initiated via android_device_connect_async API. The 75 * main difference with the synchronous connection is that this API will not fail 76 * if connection is not immediately available. If connection is not available at 77 * the time of the call, the API will schedule a retry (based on a timer), and 78 * will continue reprying untill connection becomes available, or until an error 79 * occurs that prevent further retries. 80 * 81 * This API should be used when ... Well, whenever appropriate. For instance, 82 * sensor emulation will use this API to restore lost connection with the device. 83 * 84 * NOTE: Asynchronous connection will complete no sooner than the emulator enters 85 * its main loop. 86 * 87 * IV EXCHANGE PROTOCOL. 88 * Obviously, there must be some application running on the device, that implements 89 * a socket server listening on the forwarded TCP port, and accepting the clients. 90 * 91 * IV.I Query vs. event channel. 92 * The exchange protocol assumes, that when a channel is connected, it will 93 * identify itself by sending a string containing channel type. Only after such 94 * identification has been made the channel becomes available for use. 95 * 96 * IV.II Message format. 97 * All data that is transferred in both directions over both channels are zero- 98 * terminated strings. 99 */ 100 101 #include "qemu-common.h" 102 #include "android/async-utils.h" 103 #include "android/utils/debug.h" 104 105 /* TCP port reserved for sensor emulation. */ 106 #define AD_SENSOR_PORT 1968 107 108 /* Definis infinite timeout. */ 109 #define AD_INFINITE_WAIT -1 110 111 /* Enumerates results of asynchronous data transfer. 112 */ 113 typedef enum ATResult { 114 /* Data transfer has been completed. */ 115 ATR_SUCCESS, 116 /* Socket got disconnected while data transfer has been in progress. */ 117 ATR_DISCONNECT, 118 /* An I/O error has occured. 'errno' contains error value. */ 119 ATR_IO_ERROR, 120 } ATResult; 121 122 /* Android device descriptor. */ 123 typedef struct AndroidDevice AndroidDevice; 124 125 /******************************************************************************** 126 * Callback declarations 127 *******************************************************************************/ 128 129 /* Callback routine that is invoked when android device is connected, or failed 130 * to connect. As discussed above, this callback is called when both, query and 131 * event channels have been connected. This callback is used only for asynchronous 132 * connections. 133 * Param: 134 * opaque - Opaque pointer that was passed to android_device_init API. 135 * ad - Androd device descriptor for the connection. 136 * failure - Zero indicates that connection with the device has been successfuly 137 * established. Non-zero vaule passed in this parameter indicates a failure, 138 * and contains 'errno'-reason for failure. 139 */ 140 typedef void (*device_connected_cb)(void* opaque, AndroidDevice* ad, int failure); 141 142 /* Callback routine that is invoked on an event received in the event channel. 143 * NOTE: It's important to check 'errno' in this callback. If 'errno' is set to 144 * ENOMEM, this signals that buffer passed to android_device_listen was too small 145 * to contain the entire event message. 146 * Param: 147 * opaque - Opaque pointer that was passed to android_device_init API. 148 * ad - Androd device descriptor for the connection. 149 * msg - Event message (a zero-terminated string) received from the device. 150 * msgsize - Event message size (including zero-terminator). 151 */ 152 typedef void (*event_cb)(void* opaque, AndroidDevice* ad, char* msg, int msgsize); 153 154 /* Callback routine that is invoked when an I/O failure occurs on a channel. 155 * Note that this callback will not be invoked on connection failures. 156 * Param: 157 * opaque - Opaque pointer that was passed to android_device_init API. 158 * ad - Android device instance 159 * failure - Contains 'errno' indicating the reason for failure. 160 */ 161 typedef void (*io_failure_cb)(void* opaque, AndroidDevice* ad, int failure); 162 163 /* Callback routine that is invoked when an asynchronous data send has been 164 * completed. 165 * Param: 166 * opaque - An opaque pointer associated with the data. 167 * res - Result of data transfer. 168 * data, size - Transferred data buffer. 169 * sent - Number of sent bytes. 170 */ 171 typedef void (*async_send_cb)(void* opaque, 172 ATResult res, 173 void* data, 174 int size, 175 int sent); 176 177 /******************************************************************************** 178 * Android Device API. 179 *******************************************************************************/ 180 181 /* Initializes android device descriptor. 182 * Param: 183 * opaque - An opaque pointer to associate with the descriptor. This pointer 184 * will be passed to all callbacks (see above) that were invoked by the 185 * initializing android device instance. 186 * port - TCP port to use for connection. 187 * on_io_failure - Callback to invoke when an I/O failure occurs on a channel 188 * used by the initializing android device instance. Can be NULL. 189 * Return: 190 * Initialized android device descriptor on success, or NULL on failure. 191 */ 192 extern AndroidDevice* android_device_init(void* opaque, 193 int port, 194 io_failure_cb on_io_failure); 195 196 /* Disconnects and destroys android device descriptor. 197 * Param: 198 * ad - Android device descriptor, returned from android_device_init API. 199 * Note that memory allocated for this descriptor will be freed in this 200 * routine. 201 */ 202 extern void android_device_destroy(AndroidDevice* ad); 203 204 /* Synchronously connects to the device. See notes above for more details. 205 * Param: 206 * ad - Android device descriptor, returned from android_device_init API. 207 * to - Milliseconds to wait for connection to be established. 208 * Return: 209 * Zero on success, or non-zero value on failure with 'errno' properly set. 210 */ 211 extern int android_device_connect_sync(AndroidDevice* ad, int to); 212 213 /* Asynchronously connects to the device. See notes above for more details. 214 * Param: 215 * ad - Android device descriptor, returned from android_device_init API. 216 * on_connected - Callback to invoke when connection is completed (i,e, both, 217 * event, and query channels have been connected). This parameter can be 218 * NULL. Note that connection errors will be also reported through this 219 * callback. Also note that this callback will be invoked even if this 220 * routine returns with a failure. 221 * Return: 222 * Zero on success, or non-zero value on failure with 'errno' properly set. 223 */ 224 extern int android_device_connect_async(AndroidDevice* ad, 225 device_connected_cb on_connected); 226 227 /* Disconnects from the android device. 228 * Param: 229 * ad - Android device descriptor, returned from android_device_init API. 230 */ 231 extern void android_device_disconnect(AndroidDevice* ad); 232 233 /* Queries the device via query channel. 234 * Param: 235 * ad - Android device descriptor, returned from android_device_init API. 236 * query - Zero-terminated query string. 237 * buff, buffsize - Buffer where to receive the response to the query. 238 * to - Milliseconds to wait for the entire query to complete. 239 * Return: 240 * Zero on success, or non-zero value on failure with 'errno' properly set: 241 * - 0 Indicates that the server has failed the query. 242 * - Anything else indicates an I/O error. 243 */ 244 extern int android_device_query(AndroidDevice* ad, 245 const char* query, 246 char* buff, 247 size_t buffsize, 248 int to); 249 250 /* Starts a query that may require more than one buffer transfer. 251 * This routine allows to initiate a query that may require more than one call to 252 * send_data, or may have a format that differs from the usual (a zero-terminated 253 * string). For instance, sending a BLOB data should use this routine to start a 254 * a query, then use android_device_send_query_data to transfer the data, and 255 * then call android_device_complete_query to obtain the response. 256 * Param: 257 * ad - Android device descriptor, returned from android_device_init API. 258 * query - Zero-terminated query string. 259 * to - Milliseconds to wait for the entire query to complete. 260 * Return: 261 * Zero on success, or non-zero value on failure with 'errno' properly set: 262 * - 0 Indicates that the server has failed the query. 263 * - Anything else indicates an I/O error. 264 */ 265 extern int android_device_start_query(AndroidDevice* ad, 266 const char* query, 267 int to); 268 269 /* Sends data block for a query started with android_device_start_query 270 * Param: 271 * ad - Android device descriptor, returned from android_device_init API. 272 * data, size - Data to transfer. 273 * Return: 274 * Number of bytes transferred on success, or -1 on failure with errno 275 * containing the reason for failure. 276 */ 277 extern int android_device_send_query_data(AndroidDevice* ad, 278 const void* data, 279 int size); 280 281 /* Completes a query started with android_device_start_query, and receives the 282 * query response. 283 * Param: 284 * ad - Android device descriptor, returned from android_device_init API. 285 * buff, buffsize - Buffer where to receive the response to the query. 286 * Return: 287 * Zero on success, or non-zero value on failure with 'errno' properly set. 288 */ 289 extern int android_device_complete_query(AndroidDevice* ad, char* buff, size_t buffsize); 290 291 /* Start listening on the event channel. 292 * Param: 293 * ad - Android device descriptor, returned from android_device_init API. 294 * buff, buffsize - Buffer where to receive the event message. 295 * on_event - Callback to invoke on event. Note that this callback will be 296 * invoked even if this routine returns with a failure. 297 * Return: 298 * Zero on success, or non-zero value on failure with 'errno' properly set. 299 */ 300 extern int android_device_listen(AndroidDevice* ad, 301 char* buff, 302 int buffsize, 303 event_cb on_event); 304 305 /* Asynchronously sends data to the android device. 306 * Param: 307 * ad - Android device descriptor, returned from android_device_init API. 308 * data, size - Buffer containing data to send. 309 * free_on_close - A boolean flag indicating whether the data buffer should be 310 * freed upon data transfer completion. 311 * cb - Callback to invoke when data transfer is completed. 312 * opaque - An opaque pointer to pass to the transfer completion callback. 313 */ 314 extern int android_device_send_async(AndroidDevice* ad, 315 void* data, 316 int size, 317 int free_on_close, 318 async_send_cb cb, 319 void* opaque); 320 321 #endif /* ANDROID_ANDROID_DEVICE_H_ */ 322
