SERVICES.TXT 9.2 KB

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