blob: 63000f2935725aaa15c597a237f1b421df32e32c [file] [log] [blame]
The Android Open Source Project9ca14dc2009-03-03 19:32:55 -08001This file tries to document all requests a client can make
2to the ADB server of an adbd daemon. See the OVERVIEW.TXT document
3to understand what's going on here.
4
5HOST SERVICES:
6
7host:version
8 Ask the ADB server for its internal version number.
9
10 As a special exception, the server will respond with a 4-byte
11 hex string corresponding to its internal version number, without
12 any OKAY or FAIL.
13
14host:kill
15 Ask the ADB server to quit immediately. This is used when the
16 ADB client detects that an obsolete server is running after an
17 upgrade.
18
19host:devices
Scott Anderson6dfaf4b2012-04-20 11:21:14 -070020host:devices-l
The Android Open Source Project9ca14dc2009-03-03 19:32:55 -080021 Ask to return the list of available Android devices and their
Scott Anderson6dfaf4b2012-04-20 11:21:14 -070022 state. devices-l includes the device paths in the state.
23 After the OKAY, this is followed by a 4-byte hex len,
The Android Open Source Project9ca14dc2009-03-03 19:32:55 -080024 and a string that will be dumped as-is by the client, then
25 the connection is closed
26
27host:track-devices
28 This is a variant of host:devices which doesn't close the
29 connection. Instead, a new device list description is sent
30 each time a device is added/removed or the state of a given
31 device changes (hex4 + content). This allows tools like DDMS
32 to track the state of connected devices in real-time without
33 polling the server repeatedly.
34
35host:emulator:<port>
36 This is a special query that is sent to the ADB server when a
37 new emulator starts up. <port> is a decimal number corresponding
38 to the emulator's ADB control port, i.e. the TCP port that the
39 emulator will forward automatically to the adbd daemon running
40 in the emulator system.
41
42 This mechanism allows the ADB server to know when new emulator
43 instances start.
44
45host:transport:<serial-number>
46 Ask to switch the connection to the device/emulator identified by
47 <serial-number>. After the OKAY response, every client request will
48 be sent directly to the adbd daemon running on the device.
49 (Used to implement the -s option)
50
51host:transport-usb
52 Ask to switch the connection to one device connected through USB
53 to the host machine. This will fail if there are more than one such
54 devices. (Used to implement the -d convenience option)
55
56host:transport-local
57 Ask to switch the connection to one emulator connected through TCP.
58 This will fail if there is more than one such emulator instance
59 running. (Used to implement the -e convenience option)
60
61host:transport-any
62 Another host:transport variant. Ask to switch the connection to
63 either the device or emulator connect to/running on the host.
64 Will fail if there is more than one such device/emulator available.
65 (Used when neither -s, -d or -e are provided)
66
67host-serial:<serial-number>:<request>
68 This is a special form of query, where the 'host-serial:<serial-number>:'
69 prefix can be used to indicate that the client is asking the ADB server
70 for information related to a specific device. <request> can be in one
71 of the format described below.
72
73host-usb:<request>
74 A variant of host-serial used to target the single USB device connected
75 to the host. This will fail if there is none or more than one.
76
77host-local:<request>
78 A variant of host-serial used to target the single emulator instance
Brian Carlstrom9633bca2010-04-26 09:33:47 -070079 running on the host. This will fail if there is none or more than one.
The Android Open Source Project9ca14dc2009-03-03 19:32:55 -080080
81host:<request>
82 When asking for information related to a device, 'host:' can also be
83 interpreted as 'any single device or emulator connected to/running on
84 the host'.
85
86<host-prefix>:get-product
87 XXX
88
89<host-prefix>:get-serialno
90 Returns the serial number of the corresponding device/emulator.
91 Note that emulator serial numbers are of the form "emulator-5554"
92
Scott Anderson6dfaf4b2012-04-20 11:21:14 -070093<host-prefix>:get-devpath
94 Returns the device path of the corresponding device/emulator.
95
The Android Open Source Project9ca14dc2009-03-03 19:32:55 -080096<host-prefix>:get-state
97 Returns the state of a given device as a string.
98
99<host-prefix>:forward:<local>;<remote>
100 Asks the ADB server to forward local connections from <local>
101 to the <remote> address on a given device.
102
103 There, <host-prefix> can be one of the
104 host-serial/host-usb/host-local/host prefixes as described previously
105 and indicates which device/emulator to target.
106
107 the format of <local> is one of:
108
109 tcp:<port> -> TCP connection on localhost:<port>
110 local:<path> -> Unix local domain socket on <path>
111
112 the format of <remote> is one of:
113
114 tcp:<port> -> TCP localhost:<port> on device
115 local:<path> -> Unix local domain socket on device
116 jdwp:<pid> -> JDWP thread on VM process <pid>
117
118 or even any one of the local services described below.
119
David 'Digit' Turner6c489802012-11-14 15:01:55 +0100120<host-prefix>:forward:norebind:<local>;<remote>
121 Same as <host-prefix>:forward:<local>;<remote> except that it will
122 fail it there is already a forward connection from <local>.
The Android Open Source Project9ca14dc2009-03-03 19:32:55 -0800123
David 'Digit' Turner6c489802012-11-14 15:01:55 +0100124 Used to implement 'adb forward --no-rebind <local> <remote>'
125
126<host-prefix>:killforward:<local>
127 Remove any existing forward local connection from <local>.
128 This is used to implement 'adb forward --remove <local>'
129
130<host-prefix>:killforward-all
131 Remove all forward network connections.
132 This is used to implement 'adb forward --remove-all'.
133
134<host-prefix>:list-forward
135 List all existing forward connections from this server.
136 This returns something that looks like the following:
137
138 <hex4>: The length of the payload, as 4 hexadecimal chars.
139 <payload>: A series of lines of the following format:
140
141 <serial> " " <local> " " <remote> "\n"
142
143 Where <serial> is a device serial number.
144 <local> is the host-specific endpoint (e.g. tcp:9000).
145 <remote> is the device-specific endpoint.
146
147 Used to implement 'adb forward --list'.
The Android Open Source Project9ca14dc2009-03-03 19:32:55 -0800148
149LOCAL SERVICES:
150
151All the queries below assumed that you already switched the transport
152to a real device, or that you have used a query prefix as described
153above.
154
155shell:command arg1 arg2 ...
156 Run 'command arg1 arg2 ...' in a shell on the device, and return
157 its output and error streams. Note that arguments must be separated
158 by spaces. If an argument contains a space, it must be quoted with
159 double-quotes. Arguments cannot contain double quotes or things
160 will go very wrong.
161
162 Note that this is the non-interactive version of "adb shell"
163
164shell:
165 Start an interactive shell session on the device. Redirect
166 stdin/stdout/stderr as appropriate. Note that the ADB server uses
167 this to implement "adb shell", but will also cook the input before
168 sending it to the device (see interactive_shell() in commandline.c)
169
170remount:
171 Ask adbd to remount the device's filesystem in read-write mode,
172 instead of read-only. This is usually necessary before performing
173 an "adb sync" or "adb push" request.
174
175 This request may not succeed on certain builds which do not allow
176 that.
177
178dev:<path>
179 Opens a device file and connects the client directly to it for
180 read/write purposes. Useful for debugging, but may require special
Brian Carlstrom9633bca2010-04-26 09:33:47 -0700181 privileges and thus may not run on all devices. <path> is a full
The Android Open Source Project9ca14dc2009-03-03 19:32:55 -0800182 path from the root of the filesystem.
183
184tcp:<port>
185 Tries to connect to tcp port <port> on localhost.
186
187tcp:<port>:<server-name>
188 Tries to connect to tcp port <port> on machine <server-name> from
189 the device. This can be useful to debug some networking/proxy
190 issues that can only be revealed on the device itself.
191
192local:<path>
193 Tries to connect to a Unix domain socket <path> on the device
194
195localreserved:<path>
196localabstract:<path>
197localfilesystem:<path>
198 Variants of local:<path> that are used to access other Android
199 socket namespaces.
200
The Android Open Source Project9ca14dc2009-03-03 19:32:55 -0800201framebuffer:
202 This service is used to send snapshots of the framebuffer to a client.
Brian Carlstrom9633bca2010-04-26 09:33:47 -0700203 It requires sufficient privileges but works as follow:
The Android Open Source Project9ca14dc2009-03-03 19:32:55 -0800204
205 After the OKAY, the service sends 16-byte binary structure
206 containing the following fields (little-endian format):
207
208 depth: uint32_t: framebuffer depth
209 size: uint32_t: framebuffer size in bytes
210 width: uint32_t: framebuffer width in pixels
211 height: uint32_t: framebuffer height in pixels
212
213 With the current implementation, depth is always 16, and
214 size is always width*height*2
215
216 Then, each time the client wants a snapshot, it should send
217 one byte through the channel, which will trigger the service
218 to send it 'size' bytes of framebuffer data.
219
Brian Carlstrom9633bca2010-04-26 09:33:47 -0700220 If the adbd daemon doesn't have sufficient privileges to open
The Android Open Source Project9ca14dc2009-03-03 19:32:55 -0800221 the framebuffer device, the connection is simply closed immediately.
222
The Android Open Source Project9ca14dc2009-03-03 19:32:55 -0800223jdwp:<pid>
224 Connects to the JDWP thread running in the VM of process <pid>.
225
226track-jdwp
227 This is used to send the list of JDWP pids periodically to the client.
228 The format of the returned data is the following:
229
230 <hex4>: the length of all content as a 4-char hexadecimal string
231 <content>: a series of ASCII lines of the following format:
232 <pid> "\n"
233
234 This service is used by DDMS to know which debuggable processes are running
235 on the device/emulator.
236
237 Note that there is no single-shot service to retrieve the list only once.
238
239sync:
240 This starts the file synchronisation service, used to implement "adb push"
241 and "adb pull". Since this service is pretty complex, it will be detailed
242 in a companion document named SYNC.TXT
David 'Digit' Turner963a4492013-03-21 21:07:42 +0100243
244reverse:<forward-command>
245 This implements the 'adb reverse' feature, i.e. the ability to reverse
246 socket connections from a device to the host. <forward-command> is one
247 of the forwarding commands that are described above, as in:
248
249 list-forward
250 forward:<local>;<remote>
251 forward:norebind:<local>;<remote>
252 killforward-all
253 killforward:<local>
254
255 Note that in this case, <local> corresponds to the socket on the device
256 and <remote> corresponds to the socket on the host.
257
258 The output of reverse:list-forward is the same as host:list-forward
259 except that <serial> will be just 'host'.