blob: 9fde906fdb5b1c574f3fd896343e785898e27cde [file] [log] [blame]
Vladimir Chtchetkinedb611d52011-11-01 17:35:07 -07001/*
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. */
112typedef 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 */
129typedef 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 */
141typedef 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 */
150typedef 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 */
167extern 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 */
177extern 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 */
186extern 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 */
199extern 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 */
206extern 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 */
219extern 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 */
234extern int android_device_listen(AndroidDevice* ad,
235 char* buff,
236 int buffsize,
237 event_cb on_event);
238
239#endif /* ANDROID_ANDROID_DEVICE_H_ */