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-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 89<host-prefix>:get-devpath 90 Returns the device path of the corresponding device/emulator. 91 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> 113 vsock:<CID>:<port> -> vsock on the given CID and port 114 115 or even any one of the local services described below. 116 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>. 120 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'. 145 146LOCAL SERVICES: 147 148All the queries below assumed that you already switched the transport 149to a real device, or that you have used a query prefix as described 150above. 151 152shell: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 161shell: 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 167remount: 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 175dev:<path> 176 Opens a device file and connects the client directly to it for 177 read/write purposes. Useful for debugging, but may require special 178 privileges and thus may not run on all devices. <path> is a full 179 path from the root of the filesystem. 180 181tcp:<port> 182 Tries to connect to tcp port <port> on localhost. 183 184tcp:<port>:<server-name> 185 Tries to connect to tcp port <port> on machine <server-name> from 186 the device. This can be useful to debug some networking/proxy 187 issues that can only be revealed on the device itself. 188 189local:<path> 190 Tries to connect to a Unix domain socket <path> on the device 191 192localreserved:<path> 193localabstract:<path> 194localfilesystem:<path> 195 Variants of local:<path> that are used to access other Android 196 socket namespaces. 197 198framebuffer: 199 This service is used to send snapshots of the framebuffer to a client. 200 It requires sufficient privileges but works as follow: 201 202 After the OKAY, the service sends 16-byte binary structure 203 containing the following fields (little-endian format): 204 205 depth: uint32_t: framebuffer depth 206 size: uint32_t: framebuffer size in bytes 207 width: uint32_t: framebuffer width in pixels 208 height: uint32_t: framebuffer height in pixels 209 210 With the current implementation, depth is always 16, and 211 size is always width*height*2 212 213 Then, each time the client wants a snapshot, it should send 214 one byte through the channel, which will trigger the service 215 to send it 'size' bytes of framebuffer data. 216 217 If the adbd daemon doesn't have sufficient privileges to open 218 the framebuffer device, the connection is simply closed immediately. 219 220jdwp:<pid> 221 Connects to the JDWP thread running in the VM of process <pid>. 222 223track-jdwp 224 This is used to send the list of JDWP pids periodically to the client. 225 The format of the returned data is the following: 226 227 <hex4>: the length of all content as a 4-char hexadecimal string 228 <content>: a series of ASCII lines of the following format: 229 <pid> "\n" 230 231 This service is used by DDMS to know which debuggable processes are running 232 on the device/emulator. 233 234 Note that there is no single-shot service to retrieve the list only once. 235 236sync: 237 This starts the file synchronization service, used to implement "adb push" 238 and "adb pull". Since this service is pretty complex, it will be detailed 239 in a companion document named SYNC.TXT 240 241reverse:<forward-command> 242 This implements the 'adb reverse' feature, i.e. the ability to reverse 243 socket connections from a device to the host. <forward-command> is one 244 of the forwarding commands that are described above, as in: 245 246 list-forward 247 forward:<local>;<remote> 248 forward:norebind:<local>;<remote> 249 killforward-all 250 killforward:<local> 251 252 Note that in this case, <local> corresponds to the socket on the device 253 and <remote> corresponds to the socket on the host. 254 255 The output of reverse:list-forward is the same as host:list-forward 256 except that <serial> will be just 'host'. 257