1 This file tries to document all requests a client can make 2 to the ADB server of an adbd daemon. See the OVERVIEW.TXT document 3 to understand what's going on here. 4 5 HOST SERVICES: 6 7 host: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 14 host: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 19 host:devices 20 Ask to return the list of available Android devices and their 21 state. After the OKAY, this is followed by a 4-byte hex len, 22 and a string that will be dumped as-is by the client, then 23 the connection is closed 24 25 host:track-devices 26 This is a variant 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 (hex4 + content). This allows tools like DDMS 30 to track the state of connected devices in real-time without 31 polling the server repeatedly. 32 33 host: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 43 host: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 49 host: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 54 host: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 59 host: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 65 host-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 71 host-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 75 host-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 79 host:<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-product 85 XXX 86 87 <host-prefix>:get-serialno 88 Returns the serial number of the corresponding device/emulator. 89 Note that emulator serial numbers are of the form "emulator-5554" 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 113 or even any one of the local services described below. 114 115 116 117 LOCAL SERVICES: 118 119 All the queries below assumed that you already switched the transport 120 to a real device, or that you have used a query prefix as described 121 above. 122 123 shell:command arg1 arg2 ... 124 Run 'command arg1 arg2 ...' in a shell on the device, and return 125 its output and error streams. Note that arguments must be separated 126 by spaces. If an argument contains a space, it must be quoted with 127 double-quotes. Arguments cannot contain double quotes or things 128 will go very wrong. 129 130 Note that this is the non-interactive version of "adb shell" 131 132 shell: 133 Start an interactive shell session on the device. Redirect 134 stdin/stdout/stderr as appropriate. Note that the ADB server uses 135 this to implement "adb shell", but will also cook the input before 136 sending it to the device (see interactive_shell() in commandline.c) 137 138 remount: 139 Ask adbd to remount the device's filesystem in read-write mode, 140 instead of read-only. This is usually necessary before performing 141 an "adb sync" or "adb push" request. 142 143 This request may not succeed on certain builds which do not allow 144 that. 145 146 dev:<path> 147 Opens a device file and connects the client directly to it for 148 read/write purposes. Useful for debugging, but may require special 149 privileges and thus may not run on all devices. <path> is a full 150 path from the root of the filesystem. 151 152 tcp:<port> 153 Tries to connect to tcp port <port> on localhost. 154 155 tcp:<port>:<server-name> 156 Tries to connect to tcp port <port> on machine <server-name> from 157 the device. This can be useful to debug some networking/proxy 158 issues that can only be revealed on the device itself. 159 160 local:<path> 161 Tries to connect to a Unix domain socket <path> on the device 162 163 localreserved:<path> 164 localabstract:<path> 165 localfilesystem:<path> 166 Variants of local:<path> that are used to access other Android 167 socket namespaces. 168 169 log:<name> 170 Opens one of the system logs (/dev/log/<name>) and allows the client 171 to read them directly. Used to implement 'adb logcat'. The stream 172 will be read-only for the client. 173 174 framebuffer: 175 This service is used to send snapshots of the framebuffer to a client. 176 It requires sufficient privileges but works as follow: 177 178 After the OKAY, the service sends 16-byte binary structure 179 containing the following fields (little-endian format): 180 181 depth: uint32_t: framebuffer depth 182 size: uint32_t: framebuffer size in bytes 183 width: uint32_t: framebuffer width in pixels 184 height: uint32_t: framebuffer height in pixels 185 186 With the current implementation, depth is always 16, and 187 size is always width*height*2 188 189 Then, each time the client wants a snapshot, it should send 190 one byte through the channel, which will trigger the service 191 to send it 'size' bytes of framebuffer data. 192 193 If the adbd daemon doesn't have sufficient privileges to open 194 the framebuffer device, the connection is simply closed immediately. 195 196 dns:<server-name> 197 This service is an exception because it only runs within the ADB server. 198 It is used to implement USB networking, i.e. to provide a network connection 199 to the device through the host machine (note: this is the exact opposite of 200 network tethering). 201 202 It is used to perform a gethostbyname(<address>) on the host and return 203 the corresponding IP address as a 4-byte string. 204 205 recover:<size> 206 This service is used to upload a recovery image to the device. <size> 207 must be a number corresponding to the size of the file. The service works 208 by: 209 210 - creating a file named /tmp/update 211 - reading 'size' bytes from the client and writing them to /tmp/update 212 - when everything is read successfully, create a file named /tmp/update.start 213 214 This service can only work when the device is in recovery mode. Otherwise, 215 the /tmp directory doesn't exist and the connection will be closed immediately. 216 217 jdwp:<pid> 218 Connects to the JDWP thread running in the VM of process <pid>. 219 220 track-jdwp 221 This is used to send the list of JDWP pids periodically to the client. 222 The format of the returned data is the following: 223 224 <hex4>: the length of all content as a 4-char hexadecimal string 225 <content>: a series of ASCII lines of the following format: 226 <pid> "\n" 227 228 This service is used by DDMS to know which debuggable processes are running 229 on the device/emulator. 230 231 Note that there is no single-shot service to retrieve the list only once. 232 233 sync: 234 This starts the file synchronisation service, used to implement "adb push" 235 and "adb pull". Since this service is pretty complex, it will be detailed 236 in a companion document named SYNC.TXT 237
