• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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