The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 1 | This file tries to document all requests a client can make |
| 2 | to the ADB server of an adbd daemon. See the OVERVIEW.TXT document |
| 3 | to understand what's going on here. |
| 4 | |
| 5 | HOST SERVICES: |
| 6 | |
| 7 | host: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 | |
| 14 | host: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 | |
| 19 | host: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 | |
| 25 | host: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 | |
| 33 | host: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 | |
| 43 | host: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 | |
| 49 | host: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 | |
| 54 | host: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 | |
| 59 | host: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 | |
| 65 | host-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 | |
| 71 | host-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 | |
| 75 | host-local:<request> |
| 76 | A variant of host-serial used to target the single emulator instance |
Brian Carlstrom | 26bb6e9 | 2010-04-26 09:33:47 -0700 | [diff] [blame] | 77 | running on the host. This will fail if there is none or more than one. |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 78 | |
| 79 | host:<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 | |
| 117 | LOCAL SERVICES: |
| 118 | |
| 119 | All the queries below assumed that you already switched the transport |
| 120 | to a real device, or that you have used a query prefix as described |
| 121 | above. |
| 122 | |
| 123 | shell: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 | |
| 132 | shell: |
| 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 | |
| 138 | remount: |
| 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 | |
| 146 | dev:<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 |
Brian Carlstrom | 26bb6e9 | 2010-04-26 09:33:47 -0700 | [diff] [blame] | 149 | privileges and thus may not run on all devices. <path> is a full |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 150 | path from the root of the filesystem. |
| 151 | |
| 152 | tcp:<port> |
| 153 | Tries to connect to tcp port <port> on localhost. |
| 154 | |
| 155 | tcp:<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 | |
| 160 | local:<path> |
| 161 | Tries to connect to a Unix domain socket <path> on the device |
| 162 | |
| 163 | localreserved:<path> |
| 164 | localabstract:<path> |
| 165 | localfilesystem:<path> |
| 166 | Variants of local:<path> that are used to access other Android |
| 167 | socket namespaces. |
| 168 | |
| 169 | log:<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 | |
| 174 | framebuffer: |
| 175 | This service is used to send snapshots of the framebuffer to a client. |
Brian Carlstrom | 26bb6e9 | 2010-04-26 09:33:47 -0700 | [diff] [blame] | 176 | It requires sufficient privileges but works as follow: |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 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 | |
Brian Carlstrom | 26bb6e9 | 2010-04-26 09:33:47 -0700 | [diff] [blame] | 193 | If the adbd daemon doesn't have sufficient privileges to open |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 194 | the framebuffer device, the connection is simply closed immediately. |
| 195 | |
| 196 | dns:<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 |
Brian Carlstrom | 26bb6e9 | 2010-04-26 09:33:47 -0700 | [diff] [blame] | 200 | network tethering). |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 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 | |
| 205 | recover:<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 |
Brian Carlstrom | 26bb6e9 | 2010-04-26 09:33:47 -0700 | [diff] [blame] | 212 | - when everything is read successfully, create a file named /tmp/update.start |
The Android Open Source Project | dd7bc33 | 2009-03-03 19:32:55 -0800 | [diff] [blame] | 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 | |
| 217 | jdwp:<pid> |
| 218 | Connects to the JDWP thread running in the VM of process <pid>. |
| 219 | |
| 220 | track-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 | |
| 233 | sync: |
| 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 |