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