1This 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
20    Ask to return the list of available Android devices and their
21    state. After the OKAY, this is followed by a 4-byte hex len,
22    and a string that will be dumped as-is by the client, then
23    the connection is closed
24
25host:track-devices
26    This is a variant of host:devices which doesn't close the
27    connection. Instead, a new device list description is sent
28    each time a device is added/removed or the state of a given
29    device changes (hex4 + content). This allows tools like DDMS
30    to track the state of connected devices in real-time without
31    polling the server repeatedly.
32
33host:emulator:<port>
34    This is a special query that is sent to the ADB server when a
35    new emulator starts up. <port> is a decimal number corresponding
36    to the emulator's ADB control port, i.e. the TCP port that the
37    emulator will forward automatically to the adbd daemon running
38    in the emulator system.
39
40    This mechanism allows the ADB server to know when new emulator
41    instances start.
42
43host:transport:<serial-number>
44    Ask to switch the connection to the device/emulator identified by
45    <serial-number>. After the OKAY response, every client request will
46    be sent directly to the adbd daemon running on the device.
47    (Used to implement the -s option)
48
49host:transport-usb
50    Ask to switch the connection to one device connected through USB
51    to the host machine. This will fail if there are more than one such
52    devices. (Used to implement the -d convenience option)
53
54host:transport-local
55    Ask to switch the connection to one emulator connected through TCP.
56    This will fail if there is more than one such emulator instance
57    running. (Used to implement the -e convenience option)
58
59host:transport-any
60    Another host:transport variant. Ask to switch the connection to
61    either the device or emulator connect to/running on the host.
62    Will fail if there is more than one such device/emulator available.
63    (Used when neither -s, -d or -e are provided)
64
65host-serial:<serial-number>:<request>
66    This is a special form of query, where the 'host-serial:<serial-number>:'
67    prefix can be used to indicate that the client is asking the ADB server
68    for information related to a specific device. <request> can be in one
69    of the format described below.
70
71host-usb:<request>
72    A variant of host-serial used to target the single USB device connected
73    to the host. This will fail if there is none or more than one.
74
75host-local:<request>
76    A variant of host-serial used to target the single emulator instance
77    running on the host. This will fail if there is none or more than one.
78
79host:<request>
80    When asking for information related to a device, 'host:' can also be
81    interpreted as 'any single device or emulator connected to/running on
82    the host'.
83
84<host-prefix>:get-product
85    XXX
86
87<host-prefix>:get-serialno
88    Returns the serial number of the corresponding device/emulator.
89    Note that emulator serial numbers are of the form "emulator-5554"
90
91<host-prefix>:get-state
92    Returns the state of a given device as a string.
93
94<host-prefix>:forward:<local>;<remote>
95    Asks the ADB server to forward local connections from <local>
96    to the <remote> address on a given device.
97
98    There, <host-prefix> can be one of the
99    host-serial/host-usb/host-local/host prefixes as described previously
100    and indicates which device/emulator to target.
101
102    the format of <local> is one of:
103
104        tcp:<port>      -> TCP connection on localhost:<port>
105        local:<path>    -> Unix local domain socket on <path>
106
107    the format of <remote> is one of:
108
109        tcp:<port>      -> TCP localhost:<port> on device
110        local:<path>    -> Unix local domain socket on device
111        jdwp:<pid>      -> JDWP thread on VM process <pid>
112
113    or even any one of the local services described below.
114
115
116
117LOCAL SERVICES:
118
119All the queries below assumed that you already switched the transport
120to a real device, or that you have used a query prefix as described
121above.
122
123shell:command arg1 arg2 ...
124    Run 'command arg1 arg2 ...' in a shell on the device, and return
125    its output and error streams. Note that arguments must be separated
126    by spaces. If an argument contains a space, it must be quoted with
127    double-quotes. Arguments cannot contain double quotes or things
128    will go very wrong.
129
130    Note that this is the non-interactive version of "adb shell"
131
132shell:
133    Start an interactive shell session on the device. Redirect
134    stdin/stdout/stderr as appropriate. Note that the ADB server uses
135    this to implement "adb shell", but will also cook the input before
136    sending it to the device (see interactive_shell() in commandline.c)
137
138remount:
139    Ask adbd to remount the device's filesystem in read-write mode,
140    instead of read-only. This is usually necessary before performing
141    an "adb sync" or "adb push" request.
142
143    This request may not succeed on certain builds which do not allow
144    that.
145
146dev:<path>
147    Opens a device file and connects the client directly to it for
148    read/write purposes. Useful for debugging, but may require special
149    privileges and thus may not run on all devices. <path> is a full
150    path from the root of the filesystem.
151
152tcp:<port>
153    Tries to connect to tcp port <port> on localhost.
154
155tcp:<port>:<server-name>
156    Tries to connect to tcp port <port> on machine <server-name> from
157    the device. This can be useful to debug some networking/proxy
158    issues that can only be revealed on the device itself.
159
160local:<path>
161    Tries to connect to a Unix domain socket <path> on the device
162
163localreserved:<path>
164localabstract:<path>
165localfilesystem:<path>
166    Variants of local:<path> that are used to access other Android
167    socket namespaces.
168
169log:<name>
170    Opens one of the system logs (/dev/log/<name>) and allows the client
171    to read them directly. Used to implement 'adb logcat'. The stream
172    will be read-only for the client.
173
174framebuffer:
175    This service is used to send snapshots of the framebuffer to a client.
176    It requires sufficient privileges but works as follow:
177
178      After the OKAY, the service sends 16-byte binary structure
179      containing the following fields (little-endian format):
180
181            depth:   uint32_t:    framebuffer depth
182            size:    uint32_t:    framebuffer size in bytes
183            width:   uint32_t:    framebuffer width in pixels
184            height:  uint32_t:    framebuffer height in pixels
185
186      With the current implementation, depth is always 16, and
187      size is always width*height*2
188
189      Then, each time the client wants a snapshot, it should send
190      one byte through the channel, which will trigger the service
191      to send it 'size' bytes of framebuffer data.
192
193      If the adbd daemon doesn't have sufficient privileges to open
194      the framebuffer device, the connection is simply closed immediately.
195
196dns:<server-name>
197    This service is an exception because it only runs within the ADB server.
198    It is used to implement USB networking, i.e. to provide a network connection
199    to the device through the host machine (note: this is the exact opposite of
200    network tethering).
201
202    It is used to perform a gethostbyname(<address>) on the host and return
203    the corresponding IP address as a 4-byte string.
204
205recover:<size>
206    This service is used to upload a recovery image to the device. <size>
207    must be a number corresponding to the size of the file. The service works
208    by:
209
210       - creating a file named /tmp/update
211       - reading 'size' bytes from the client and writing them to /tmp/update
212       - when everything is read successfully, create a file named /tmp/update.start
213
214    This service can only work when the device is in recovery mode. Otherwise,
215    the /tmp directory doesn't exist and the connection will be closed immediately.
216
217jdwp:<pid>
218    Connects to the JDWP thread running in the VM of process <pid>.
219
220track-jdwp
221    This is used to send the list of JDWP pids periodically to the client.
222    The format of the returned data is the following:
223
224        <hex4>:    the length of all content as a 4-char hexadecimal string
225        <content>: a series of ASCII lines of the following format:
226                        <pid> "\n"
227
228    This service is used by DDMS to know which debuggable processes are running
229    on the device/emulator.
230
231    Note that there is no single-shot service to retrieve the list only once.
232
233sync:
234    This starts the file synchronisation service, used to implement "adb push"
235    and "adb pull". Since this service is pretty complex, it will be detailed
236    in a companion document named SYNC.TXT
237