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