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 10host: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 15host:devices 16host:devices-l 17 Ask to return the list of available Android devices and their 18 state. devices-l includes the device paths in the state. 19 After the OKAY, this is followed by a 4-byte hex len, 20 and a string that will be dumped as-is by the client, then 21 the connection is closed 22 23host:track-devices 24host:track-devices-proto-binary 25host:track-devices-proto-text 26 These are variants 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. 30 Variant [-proto-binary] is binary protobuf format. 31 Variant [-proto-text] is text protobuf format. 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-serialno 85 Returns the serial number of the corresponding device/emulator. 86 Note that emulator serial numbers are of the form "emulator-5554" 87 88<host-prefix>:get-devpath 89 Returns the device path of the corresponding device/emulator. 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 vsock:<CID>:<port> -> vsock on the given CID and port 113 114 or even any one of the local services described below. 115 116<host-prefix>:forward:norebind:<local>;<remote> 117 Same as <host-prefix>:forward:<local>;<remote> except that it will 118 fail it there is already a forward connection from <local>. 119 120 Used to implement 'adb forward --no-rebind <local> <remote>' 121 122<host-prefix>:killforward:<local> 123 Remove any existing forward local connection from <local>. 124 This is used to implement 'adb forward --remove <local>' 125 126<host-prefix>:killforward-all 127 Remove all forward network connections. 128 This is used to implement 'adb forward --remove-all'. 129 130<host-prefix>:list-forward 131 List all existing forward connections from this server. 132 This returns something that looks like the following: 133 134 <hex4>: The length of the payload, as 4 hexadecimal chars. 135 <payload>: A series of lines of the following format: 136 137 <serial> " " <local> " " <remote> "\n" 138 139 Where <serial> is a device serial number. 140 <local> is the host-specific endpoint (e.g. tcp:9000). 141 <remote> is the device-specific endpoint. 142 143 Used to implement 'adb forward --list'. 144 145LOCAL SERVICES: 146 147All the queries below assumed that you already switched the transport 148to a real device, or that you have used a query prefix as described 149above. 150 151shell:command arg1 arg2 ... 152 Run 'command arg1 arg2 ...' in a shell on the device, and return 153 its output and error streams. Note that arguments must be separated 154 by spaces. If an argument contains a space, it must be quoted with 155 double-quotes. Arguments cannot contain double quotes or things 156 will go very wrong. 157 158 Note that this is the non-interactive version of "adb shell" 159 160shell: 161 Start an interactive shell session on the device. Redirect 162 stdin/stdout/stderr as appropriate. Note that the ADB server uses 163 this to implement "adb shell", but will also cook the input before 164 sending it to the device (see interactive_shell() in commandline.c) 165 166shell,v2: (API>=24) 167 Variant of shell service which uses "shell protocol" in order to 168 differentiate stdin, stderr, and also retrieve exit code. 169 170exec: 171 Variant of shell which uses a raw PTY in order to not mangle output. 172 173abb: (API>=30) 174 Direct connection to Binder on device. This service does not use space 175 for parameter separator but "\u0000". Example: 176 abb:package0install-create 177 178abb_exec: (API>=30) 179 Variant of abb. Use a raw PTY in order to not mangle output. Example: 180 abb_exec:package0install-write 181 182remount: 183 Ask adbd to remount the device's filesystem in read-write mode, 184 instead of read-only. This is usually necessary before performing 185 an "adb sync" or "adb push" request. 186 187 This request may not succeed on certain builds which do not allow 188 that. 189 190dev:<path> 191 Opens a device file and connects the client directly to it for 192 read/write purposes. Useful for debugging, but may require special 193 privileges and thus may not run on all devices. <path> is a full 194 path from the root of the filesystem. Besides debugging this is 195 useful for allowing test automation running on host (not Android 196 device) to directly interact with the device file when a 197 non-trivial protocol is needed and adb shell is not suitable. Use 198 cases: factory tests for device peripherals, emulated peripheral 199 control (cuttlefish) for test automation. 200 201dev-raw:<path> 202 Similar with dev:<path>, the only difference being that the device 203 is opened in raw tty mode. Useful when default tty settings 204 interferes with protocol that is used to control the device. 205 206tcp:<port> 207 Tries to connect to tcp port <port> on localhost. 208 209tcp:<port>:<server-name> 210 Tries to connect to tcp port <port> on machine <server-name> from 211 the device. This can be useful to debug some networking/proxy 212 issues that can only be revealed on the device itself. 213 214local:<path> 215 Tries to connect to a Unix domain socket <path> on the device 216 217localreserved:<path> 218localabstract:<path> 219localfilesystem:<path> 220 Variants of local:<path> that are used to access other Android 221 socket namespaces. 222 223framebuffer: 224 This service is used to send snapshots of the framebuffer to a client. 225 It requires sufficient privileges but works as follow: 226 227 After the OKAY, the service sends 16-byte binary structure 228 containing the following fields (little-endian format): 229 230 depth: uint32_t: framebuffer depth 231 size: uint32_t: framebuffer size in bytes 232 width: uint32_t: framebuffer width in pixels 233 height: uint32_t: framebuffer height in pixels 234 235 With the current implementation, depth is always 16, and 236 size is always width*height*2 237 238 Then, each time the client wants a snapshot, it should send 239 one byte through the channel, which will trigger the service 240 to send it 'size' bytes of framebuffer data. 241 242 If the adbd daemon doesn't have sufficient privileges to open 243 the framebuffer device, the connection is simply closed immediately. 244 245jdwp:<pid> 246 Connects to the JDWP thread running in the VM of process <pid>. 247 248track-jdwp 249 This is used to send the list of JDWP pids periodically to the client. 250 The format of the returned data is the following: 251 252 <hex4>: the length of all content as a 4-char hexadecimal string 253 <content>: a series of ASCII lines of the following format: 254 <pid> "\n" 255 256 This service is used by DDMS to know which debuggable processes are running 257 on the device/emulator. 258 259 Note that there is no single-shot service to retrieve the list only once. 260 261track-app: 262 Improved version of "track-jdwp" service which also mentions whether the 263 app is profileable and its architecture. Each time the list changes, 264 a new messeage is sent (this service never stops). 265 266 Each message features a hex4 length prefix followed by a 267 binary protocol buffer. e.g.: 268 269 process { 270 pid: 18595 271 debuggable: true 272 architecture: "arm64" 273 } 274 process { 275 pid: 18407 276 debuggable: true 277 profileable: true 278 architecture: "arm64" 279 } 280 281 Note: Generate a parser from [app_processes.proto]. 282 283sync: 284 This starts the file synchronization service, used to implement "adb push" 285 and "adb pull". Since this service is pretty complex, it will be detailed 286 in a companion document named SYNC.TXT 287 288reverse:<forward-command> 289 This implements the 'adb reverse' feature, i.e. the ability to reverse 290 socket connections from a device to the host. <forward-command> is one 291 of the forwarding commands that are described above, as in: 292 293 list-forward 294 forward:<local>;<remote> 295 forward:norebind:<local>;<remote> 296 killforward-all 297 killforward:<local> 298 299 Note that in this case, <local> corresponds to the socket on the device 300 and <remote> corresponds to the socket on the host. 301 302 The output of reverse:list-forward is the same as host:list-forward 303 except that <serial> will be just 'host'. 304