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