Home | History | Annotate | Download | only in adb
      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 host: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 
     27 host: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 
     35 host: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 
     45 host: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 
     51 host: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 
     56 host: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 
     61 host: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 
     67 host-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 
     73 host-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 
     77 host-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 
     81 host:<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 
    149 LOCAL SERVICES:
    150 
    151 All the queries below assumed that you already switched the transport
    152 to a real device, or that you have used a query prefix as described
    153 above.
    154 
    155 shell: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 
    164 shell:
    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 
    170 remount:
    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 
    178 dev:<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 
    184 tcp:<port>
    185     Tries to connect to tcp port <port> on localhost.
    186 
    187 tcp:<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 
    192 local:<path>
    193     Tries to connect to a Unix domain socket <path> on the device
    194 
    195 localreserved:<path>
    196 localabstract:<path>
    197 localfilesystem:<path>
    198     Variants of local:<path> that are used to access other Android
    199     socket namespaces.
    200 
    201 framebuffer:
    202     This service is used to send snapshots of the framebuffer to a client.
    203     It requires sufficient privileges but works as follow:
    204 
    205       After the OKAY, the service sends 16-byte binary structure
    206       containing the following fields (little-endian format):
    207 
    208             depth:   uint32_t:    framebuffer depth
    209             size:    uint32_t:    framebuffer size in bytes
    210             width:   uint32_t:    framebuffer width in pixels
    211             height:  uint32_t:    framebuffer height in pixels
    212 
    213       With the current implementation, depth is always 16, and
    214       size is always width*height*2
    215 
    216       Then, each time the client wants a snapshot, it should send
    217       one byte through the channel, which will trigger the service
    218       to send it 'size' bytes of framebuffer data.
    219 
    220       If the adbd daemon doesn't have sufficient privileges to open
    221       the framebuffer device, the connection is simply closed immediately.
    222 
    223 jdwp:<pid>
    224     Connects to the JDWP thread running in the VM of process <pid>.
    225 
    226 track-jdwp
    227     This is used to send the list of JDWP pids periodically to the client.
    228     The format of the returned data is the following:
    229 
    230         <hex4>:    the length of all content as a 4-char hexadecimal string
    231         <content>: a series of ASCII lines of the following format:
    232                         <pid> "\n"
    233 
    234     This service is used by DDMS to know which debuggable processes are running
    235     on the device/emulator.
    236 
    237     Note that there is no single-shot service to retrieve the list only once.
    238 
    239 sync:
    240     This starts the file synchronisation service, used to implement "adb push"
    241     and "adb pull". Since this service is pretty complex, it will be detailed
    242     in a companion document named SYNC.TXT
    243 
    244 reverse:<forward-command>
    245     This implements the 'adb reverse' feature, i.e. the ability to reverse
    246     socket connections from a device to the host. <forward-command> is one
    247     of the forwarding commands that are described above, as in:
    248 
    249       list-forward
    250       forward:<local>;<remote>
    251       forward:norebind:<local>;<remote>
    252       killforward-all
    253       killforward:<local>
    254 
    255     Note that in this case, <local> corresponds to the socket on the device
    256     and <remote> corresponds to the socket on the host.
    257 
    258     The output of reverse:list-forward is the same as host:list-forward
    259     except that <serial> will be just 'host'.
    260