Vladimir Chtchetkine | db611d5 | 2011-11-01 17:35:07 -0700 | [diff] [blame] | 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 | /* Android device descriptor. */ |
| 112 | typedef struct AndroidDevice AndroidDevice; |
| 113 | |
| 114 | /******************************************************************************** |
| 115 | * Callback declarations |
| 116 | *******************************************************************************/ |
| 117 | |
| 118 | /* Callback routine that is invoked when android device is connected, or failed |
| 119 | * to connect. As discussed above, this callback is called when both, query and |
| 120 | * event channels have been connected. This callback is used only for asynchronous |
| 121 | * connections. |
| 122 | * Param: |
| 123 | * opaque - Opaque pointer that was passed to android_device_init API. |
| 124 | * ad - Androd device descriptor for the connection. |
| 125 | * failure - Zero indicates that connection with the device has been successfuly |
| 126 | * established. Non-zero vaule passed in this parameter indicates a failure, |
| 127 | * and contains 'errno'-reason for failure. |
| 128 | */ |
| 129 | typedef void (*device_connected_cb)(void* opaque, AndroidDevice* ad, int failure); |
| 130 | |
| 131 | /* Callback routine that is invoked on an event received in the event channel. |
| 132 | * NOTE: It's important to check 'errno' in this callback. If 'errno' is set to |
| 133 | * ENOMEM, this signals that buffer passed to android_device_listen was too small |
| 134 | * to contain the entire event message. |
| 135 | * Param: |
| 136 | * opaque - Opaque pointer that was passed to android_device_init API. |
| 137 | * ad - Androd device descriptor for the connection. |
| 138 | * msg - Event message (a zero-terminated string) received from the device. |
| 139 | * msgsize - Event message size (including zero-terminator). |
| 140 | */ |
| 141 | typedef void (*event_cb)(void* opaque, AndroidDevice* ad, char* msg, int msgsize); |
| 142 | |
| 143 | /* Callback routine that is invoked when an I/O failure occurs on a channel. |
| 144 | * Note that this callback will not be invoked on connection failures. |
| 145 | * Param: |
| 146 | * opaque - Opaque pointer that was passed to android_device_init API. |
| 147 | * ad - Android device instance |
| 148 | * failure - Contains 'errno' indicating the reason for failure. |
| 149 | */ |
| 150 | typedef void (*io_failure_cb)(void* opaque, AndroidDevice* ad, int failure); |
| 151 | |
| 152 | /******************************************************************************** |
| 153 | * Android Device API. |
| 154 | *******************************************************************************/ |
| 155 | |
| 156 | /* Initializes android device descriptor. |
| 157 | * Param: |
| 158 | * opaque - An opaque pointer to associate with the descriptor. This pointer |
| 159 | * will be passed to all callbacks (see above) that were invoked by the |
| 160 | * initializing android device instance. |
| 161 | * port - TCP port to use for connection. |
| 162 | * on_io_failure - Callback to invoke when an I/O failure occurs on a channel |
| 163 | * used by the initializing android device instance. Can be NULL. |
| 164 | * Return: |
| 165 | * Initialized android device descriptor on success, or NULL on failure. |
| 166 | */ |
| 167 | extern AndroidDevice* android_device_init(void* opaque, |
| 168 | int port, |
| 169 | io_failure_cb on_io_failure); |
| 170 | |
| 171 | /* Disconnects and destroys android device descriptor. |
| 172 | * Param: |
| 173 | * ad - Android device descriptor, returned from android_device_init API. |
| 174 | * Note that memory allocated for this descriptor will be freed in this |
| 175 | * routine. |
| 176 | */ |
| 177 | extern void android_device_destroy(AndroidDevice* ad); |
| 178 | |
| 179 | /* Synchronously connects to the device. See notes above for more details. |
| 180 | * Param: |
| 181 | * ad - Android device descriptor, returned from android_device_init API. |
| 182 | * to - Milliseconds to wait for connection to be established. |
| 183 | * Return: |
| 184 | * Zero on success, or non-zero value on failure with 'errno' properly set. |
| 185 | */ |
| 186 | extern int android_device_connect_sync(AndroidDevice* ad, int to); |
| 187 | |
| 188 | /* Asynchronously connects to the device. See notes above for more details. |
| 189 | * Param: |
| 190 | * ad - Android device descriptor, returned from android_device_init API. |
| 191 | * on_connected - Callback to invoke when connection is completed (i,e, both, |
| 192 | * event, and query channels have been connected). This parameter can be |
| 193 | * NULL. Note that connection errors will be also reported through this |
| 194 | * callback. Also note that this callback will be invoked even if this |
| 195 | * routine returns with a failure. |
| 196 | * Return: |
| 197 | * Zero on success, or non-zero value on failure with 'errno' properly set. |
| 198 | */ |
| 199 | extern int android_device_connect_async(AndroidDevice* ad, |
| 200 | device_connected_cb on_connected); |
| 201 | |
| 202 | /* Disconnects from the android device. |
| 203 | * Param: |
| 204 | * ad - Android device descriptor, returned from android_device_init API. |
| 205 | */ |
| 206 | extern void android_device_disconnect(AndroidDevice* ad); |
| 207 | |
| 208 | /* Queries the device via query channel. |
| 209 | * Param: |
| 210 | * ad - Android device descriptor, returned from android_device_init API. |
| 211 | * query - Zero-terminated query string. |
| 212 | * buff, buffsize - Buffer where to receive the response to the query. |
| 213 | * to - Milliseconds to wait for the entire query to complete. |
| 214 | * Return: |
| 215 | * Zero on success, or non-zero value on failure with 'errno' properly set: |
| 216 | * - 0 Indicates that the server has failed the query. |
| 217 | * - Anything else indicates an I/O error. |
| 218 | */ |
| 219 | extern int android_device_query(AndroidDevice* ad, |
| 220 | const char* query, |
| 221 | char* buff, |
| 222 | size_t buffsize, |
| 223 | int to); |
| 224 | |
| 225 | /* Start listening on the event channel. |
| 226 | * Param: |
| 227 | * ad - Android device descriptor, returned from android_device_init API. |
| 228 | * buff, buffsize - Buffer where to receive the event message. |
| 229 | * on_event - Callback to invoke on event. Note that this callback will be |
| 230 | * invoked even if this routine returns with a failure. |
| 231 | * Return: |
| 232 | * Zero on success, or non-zero value on failure with 'errno' properly set. |
| 233 | */ |
| 234 | extern int android_device_listen(AndroidDevice* ad, |
| 235 | char* buff, |
| 236 | int buffsize, |
| 237 | event_cb on_event); |
| 238 | |
| 239 | #endif /* ANDROID_ANDROID_DEVICE_H_ */ |