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