src/SERVICES.TXT

   1 This file tries to document all requests a client can make
   2 to the SDB server of an sdbd 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 SDB 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 SDB server to quit immediately. This is used when the
  16     SDB 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 SDB server when a
  35     new emulator starts up. <port> is a decimal number corresponding
  36     to the emulator's SDB control port, i.e. the TCP port that the
  37     emulator will forward automatically to the sdbd daemon running
  38     in the emulator system.
  39
  40     This mechanism allows the SDB 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 sdbd 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 SDB 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 SDB 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 "sdb shell"
 131
 132 shell:
 133     Start an interactive shell session on the device. Redirect
 134     stdin/stdout/stderr as appropriate. Note that the SDB server uses
 135     this to implement "sdb 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 sdbd to remount the device's filesystem in read-write mode,
 140     instead of read-only. This is usually necessary before performing
 141     an "sdb sync" or "sdb 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 'sdb 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 sdbd 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 SDB 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 "sdb push"
 235     and "sdb pull". Since this service is pretty complex, it will be detailed
 236     in a companion document named SYNC.TXT