AdbHelper

public final class AdbHelper
extends Object

java.lang.Object
   ↳ com.android.tradefed.device.server.AdbHelper

Helper class to handle requests and connections to adb.

AndroidDebugBridge is the public API to connection to adb, while AdbHelper does the low level stuff.

This currently uses spin-wait non-blocking I/O. A Selector would be more efficient, but seems like overkill for what we're doing here.

Summary

Nested classes

class AdbHelper.AdbResponse

Response from ADB. 

Constants

String HOST_TRANSPORT

Fields

public static final Charset DEFAULT_CHARSET

Public methods

static void createForward(InetSocketAddress adbSockAddr, IDevice device, String localPortSpec, String remotePortSpec)

Creates a port forwarding between a local and a remote port.

static AdbCommandRejectedException createHiddenException(String message, boolean errorDuringDeviceSelection)
static AdbCommandRejectedException createHiddenException(String message)
static byte[] createJdwpForwardRequest(int pid)

Creates a port forwarding request to a jdwp process.

static SocketChannel createPassThroughConnection(InetSocketAddress adbSockAddr, String deviceSerialNumber, int pid)

Creates and connects a new pass-through socket, from the host to a port on the device.

static void createReverse(InetSocketAddress adbSockAddr, IDevice device, String remotePortSpec, String localPortSpec)

Creates a port reversing between a remote and a local port.

static void executeRemoteCommand(InetSocketAddress adbSockAddr, String command, IDevice device, IShellOutputReceiver rcvr, long maxTimeToOutputResponse, TimeUnit maxTimeUnits)

Executes a shell command on the device and retrieve the output.

static void executeRemoteCommand(InetSocketAddress adbSockAddr, AdbHelper.AdbService adbService, String command, IDevice device, IShellOutputReceiver rcvr, long maxTimeout, long maxTimeToOutputResponse, TimeUnit maxTimeUnits, InputStream is)

Executes a remote command on the device and retrieve the output.

static void executeRemoteCommand(InetSocketAddress adbSockAddr, String command, IDevice device, IShellOutputReceiver rcvr, long maxTimeout, long maxTimeToOutputResponse, TimeUnit maxTimeUnits)

Executes a shell command on the device and retrieve the output.

static byte[] formAdbRequest(String payloadString)

Create an ASCII string preceded by four hex digits.

static String getFeatures(IDevice device)

Queries a set of supported features from the device.

static RawImage getFrameBuffer(InetSocketAddress adbSockAddr, IDevice device, long timeout, TimeUnit unit)

Retrieve the frame buffer from the device with the given timeout.

static String getHostFeatures()

Queries a set of supported features from the ADB host.

static SocketChannel open(InetSocketAddress adbSockAddr, IDevice device, int devicePort)

Create and connect a new pass-through socket, from the host to a port on the device.

static SocketChannel rawAdbService(InetSocketAddress socketAddress, IDevice device, String command, AdbHelper.AdbService service)

Invoke the service on a remote device.

static SocketChannel rawExec(InetSocketAddress socketAddress, IDevice device, String executable, String[] parameters)

Invoke the host:exec service on a remote device.

static AdbHelper.AdbResponse readAdbResponse(SocketChannel chan, boolean readDiagString)

Reads the response from ADB after a command.

static void reboot(String into, InetSocketAddress adbSockAddr, IDevice device)

Reboot the device.

static void removeForward(InetSocketAddress adbSockAddr, IDevice device, String localPortSpec)

Remove a port forwarding between a local and a remote port.

static void removeReverse(InetSocketAddress adbSockAddr, IDevice device, String remotePortSpec)

Remove a port reversing between a remote and a local port.

static void root(InetSocketAddress adbSockAddr, IDevice device)

Ask the adb demon to become root on the device.

static void setDevice(SocketChannel adbChan, IDevice device)

Given an IDevice grab the serial number and tell adb to talk to that device.

static void setDevice(SocketChannel adbChan, String deviceSerialNumber)

tells adb to talk to a specific device

static void write(SocketChannel chan, byte[] data, int length, int timeout)

Write until all data in "data" is written, the optional length is reached, the timeout expires, or the connection fails.

static void write(SocketChannel chan, byte[] data)

Write until all data in "data" is written or the connection fails or times out.

Constants

HOST_TRANSPORT

public static final String HOST_TRANSPORT

Constant Value: "host:transport:"

Fields

DEFAULT_CHARSET

public static final Charset DEFAULT_CHARSET

Public methods

createForward

public static void createForward (InetSocketAddress adbSockAddr, 
                IDevice device, 
                String localPortSpec, 
                String remotePortSpec)

Creates a port forwarding between a local and a remote port.

Parameters
adbSockAddr InetSocketAddress: the socket address to connect to adb
device IDevice: the device on which to do the port forwarding
localPortSpec String: specification of the local port to forward, should be of format tcp:
remotePortSpec String: specification of the remote port to forward to, one of: tcp: localabstract: localreserved: localfilesystem: dev: jdwp: (remote only)
Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
in case of I/O error on the connection.

createHiddenException

public static AdbCommandRejectedException createHiddenException (String message, 
                boolean errorDuringDeviceSelection)

Parameters
message String

errorDuringDeviceSelection boolean

Returns
AdbCommandRejectedException

createHiddenException

public static AdbCommandRejectedException createHiddenException (String message)

Parameters
message String

Returns
AdbCommandRejectedException

createJdwpForwardRequest

public static byte[] createJdwpForwardRequest (int pid)

Creates a port forwarding request to a jdwp process. This returns an array containing "####jwdp:{pid}".

Parameters
pid int: the jdwp process pid on the device.
Returns
byte[]

createPassThroughConnection

public static SocketChannel createPassThroughConnection (InetSocketAddress adbSockAddr, 
                String deviceSerialNumber, 
                int pid)

Creates and connects a new pass-through socket, from the host to a port on the device.

Parameters
deviceSerialNumber String: the device serial number to connect to. Can be null or empty in which case the connection will be to the first available device.
pid int: the process pid to connect to.
Returns
SocketChannel

Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
in case of I/O error on the connection.

createReverse

public static void createReverse (InetSocketAddress adbSockAddr, 
                IDevice device, 
                String remotePortSpec, 
                String localPortSpec)

Creates a port reversing between a remote and a local port.

Parameters
adbSockAddr InetSocketAddress: the socket address to connect to adb
device IDevice: the device on which to do the port reversing
remotePortSpec String: specification of the remote port to reverse to, one of: tcp: localabstract: localreserved: localfilesystem: dev: jdwp: (remote only)
localPortSpec String: specification of the local port, should be of format tcp:
Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
in case of I/O error on the connection.

executeRemoteCommand

public static void executeRemoteCommand (InetSocketAddress adbSockAddr, 
                String command, 
                IDevice device, 
                IShellOutputReceiver rcvr, 
                long maxTimeToOutputResponse, 
                TimeUnit maxTimeUnits)

Executes a shell command on the device and retrieve the output. The output is handed to rcvr as it arrives.

Parameters
adbSockAddr InetSocketAddress: the ERROR(/InetSocketAddress) to adb.
command String: the shell command to execute
device IDevice: the IDevice on which to execute the command.
rcvr IShellOutputReceiver: the IShellOutputReceiver that will receives the output of the shell command
maxTimeToOutputResponse long: max time between command output. If more time passes between command output, the method will throw ShellCommandUnresponsiveException. A value of 0 means the method will wait forever for command output and never throw.
maxTimeUnits TimeUnit: Units for non-zero maxTimeToOutputResponse values.
Throws
TimeoutException in case of timeout on the connection when sending the command.
AdbCommandRejectedException if adb rejects the command
ShellCommandUnresponsiveException in case the shell command doesn't send any output for a period longer than maxTimeToOutputResponse.
in case of I/O error on the connection.

executeRemoteCommand

public static void executeRemoteCommand (InetSocketAddress adbSockAddr, 
                AdbHelper.AdbService adbService, 
                String command, 
                IDevice device, 
                IShellOutputReceiver rcvr, 
                long maxTimeout, 
                long maxTimeToOutputResponse, 
                TimeUnit maxTimeUnits, 
                InputStream is)

Executes a remote command on the device and retrieve the output. The output is handed to rcvr as it arrives. The command is execute by the remote service identified by the adbService parameter.

Parameters
adbSockAddr InetSocketAddress: the ERROR(/InetSocketAddress) to adb.
adbService AdbHelper.AdbService: the AdbHelper.AdbService to use to run the command.
command String: the shell command to execute
device IDevice: the IDevice on which to execute the command.
rcvr IShellOutputReceiver: the IShellOutputReceiver that will receives the output of the shell command
maxTimeout long: max timeout for the full command to execute. A value of 0 means no timeout.
maxTimeToOutputResponse long: max time between command output. If more time passes between command output, the method will throw ShellCommandUnresponsiveException. A value of 0 means the method will wait forever for command output and never throw.
maxTimeUnits TimeUnit: Units for non-zero maxTimeout and maxTimeToOutputResponse values.
is InputStream: a optional ERROR(/InputStream) to be streamed up after invoking the command and before retrieving the response.
Throws
TimeoutException in case of timeout on the connection when sending the command.
AdbCommandRejectedException if adb rejects the command
ShellCommandUnresponsiveException in case the shell command doesn't send any output for a period longer than maxTimeToOutputResponse.
in case of I/O error on the connection.

executeRemoteCommand

public static void executeRemoteCommand (InetSocketAddress adbSockAddr, 
                String command, 
                IDevice device, 
                IShellOutputReceiver rcvr, 
                long maxTimeout, 
                long maxTimeToOutputResponse, 
                TimeUnit maxTimeUnits)

Executes a shell command on the device and retrieve the output. The output is handed to rcvr as it arrives.

Parameters
adbSockAddr InetSocketAddress: the ERROR(/InetSocketAddress) to adb.
command String: the shell command to execute
device IDevice: the IDevice on which to execute the command.
rcvr IShellOutputReceiver: the IShellOutputReceiver that will receives the output of the shell command
maxTimeout long: max time for the command to return. A value of 0 means no max timeout will be applied.
maxTimeToOutputResponse long: max time between command output. If more time passes between command output, the method will throw ShellCommandUnresponsiveException. A value of 0 means the method will wait forever for command output and never throw.
maxTimeUnits TimeUnit: Units for non-zero maxTimeout and maxTimeToOutputResponse values.
Throws
TimeoutException in case of timeout on the connection when sending the command.
AdbCommandRejectedException if adb rejects the command
ShellCommandUnresponsiveException in case the shell command doesn't send any output for a period longer than maxTimeToOutputResponse.
in case of I/O error on the connection.

formAdbRequest

public static byte[] formAdbRequest (String payloadString)

Create an ASCII string preceded by four hex digits. The opening "####" is the length of the rest of the string, encoded as ASCII hex (case doesn't matter).

Parameters
payloadString String

Returns
byte[]

getFeatures

public static String getFeatures (IDevice device)

Queries a set of supported features from the device.

Parameters
device IDevice: the device on which to do the port forwarding
Returns
String

Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
in case of I/O error on the connection.

getFrameBuffer

public static RawImage getFrameBuffer (InetSocketAddress adbSockAddr, 
                IDevice device, 
                long timeout, 
                TimeUnit unit)

Retrieve the frame buffer from the device with the given timeout. A timeout of 0 indicates that it will wait forever.

Parameters
adbSockAddr InetSocketAddress

device IDevice

timeout long

unit TimeUnit

Returns
RawImage

Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
in case of I/O error on the connection.

getHostFeatures

public static String getHostFeatures ()

Queries a set of supported features from the ADB host.

Returns
String

Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
in case of I/O error on the connection.

open

public static SocketChannel open (InetSocketAddress adbSockAddr, 
                IDevice device, 
                int devicePort)

Create and connect a new pass-through socket, from the host to a port on the device.

Parameters
device IDevice: the device to connect to. Can be null in which case the connection will be to the first available device.
devicePort int: the port we're opening
Returns
SocketChannel

Throws
TimeoutException in case of timeout on the connection.
in case of I/O error on the connection.
AdbCommandRejectedException if adb rejects the command

rawAdbService

public static SocketChannel rawAdbService (InetSocketAddress socketAddress, 
                IDevice device, 
                String command, 
                AdbHelper.AdbService service)

Invoke the service on a remote device. Return a socket channel that is connected to the executing process.

ddlmib relinquishes ownership of the returned SocketChannel and must be explicitly closed after use.

Parameters
device IDevice: the device to connect to. Can be null in which case the connection will be to the first available device.
command String: the command to execute
service AdbHelper.AdbService: the AdbHelper.AdbService to use to run the command.
Returns
SocketChannel

Throws
IOException
com.android.ddmlib.TimeoutException
com.android.ddmlib.AdbCommandRejectedException
AdbCommandRejectedException
TimeoutException

rawExec

public static SocketChannel rawExec (InetSocketAddress socketAddress, 
                IDevice device, 
                String executable, 
                String[] parameters)

Invoke the host:exec service on a remote device. Return a socket channel that is connected to the executing process. Note that exec service does not differentiate stdout and stderr so whatever is read from the socket can come from either output and be interleaved.

ddlmib relinquishes ownership of the returned SocketChannel and must be explicitly closed after use.

Parameters
device IDevice: the device to connect to. Can be null in which case the connection will be to the first available device.
executable String: the absolute path of the executable to run
parameters String: the parameters to get given upon execing the executable
Returns
SocketChannel

Throws
IOException
com.android.ddmlib.TimeoutException
com.android.ddmlib.AdbCommandRejectedException
AdbCommandRejectedException
TimeoutException

readAdbResponse

public static AdbHelper.AdbResponse readAdbResponse (SocketChannel chan, 
                boolean readDiagString)

Reads the response from ADB after a command.

Parameters
chan SocketChannel: The socket channel that is connected to adb.
readDiagString boolean: If true, we're expecting an OKAY response to be followed by a diagnostic string. Otherwise, we only expect the diagnostic string to follow a FAIL.
Returns
AdbHelper.AdbResponse

Throws
TimeoutException in case of timeout on the connection.
in case of I/O error on the connection.

reboot

public static void reboot (String into, 
                InetSocketAddress adbSockAddr, 
                IDevice device)

Reboot the device.

Parameters
into String: what to reboot into (recovery, bootloader). Or null to just reboot.
adbSockAddr InetSocketAddress

device IDevice

Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
in case of I/O error on the connection.

removeForward

public static void removeForward (InetSocketAddress adbSockAddr, 
                IDevice device, 
                String localPortSpec)

Remove a port forwarding between a local and a remote port.

Parameters
adbSockAddr InetSocketAddress: the socket address to connect to adb
device IDevice: the device on which to remove the port forwarding
localPortSpec String: specification of the local port that was forwarded, should be of format tcp:
Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
in case of I/O error on the connection.

removeReverse

public static void removeReverse (InetSocketAddress adbSockAddr, 
                IDevice device, 
                String remotePortSpec)

Remove a port reversing between a remote and a local port.

Parameters
adbSockAddr InetSocketAddress: the socket address to connect to adb
device IDevice: the device on which to remove the port reversing
remotePortSpec String: specification of the remote port reversed to, one of: tcp: localabstract: localreserved: localfilesystem: dev: jdwp: (remote only)
Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
in case of I/O error on the connection.

root

public static void root (InetSocketAddress adbSockAddr, 
                IDevice device)

Ask the adb demon to become root on the device. This may silently fail, and can only succeed on developer builds. See "adb root" for more information. If you need to know if succeeded, you can check the result of executeRemoteCommand on 'echo \$USER_ID', if it is 0 then adbd is running as root.

Parameters
adbSockAddr InetSocketAddress

device IDevice

Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
in case of I/O error on the connection.

setDevice

public static void setDevice (SocketChannel adbChan, 
                IDevice device)

Given an IDevice grab the serial number and tell adb to talk to that device.

Parameters
adbChan SocketChannel: the socket connection to adb.
device IDevice: the device to talk to.
Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
in case of I/O error on the connection.

setDevice

public static void setDevice (SocketChannel adbChan, 
                String deviceSerialNumber)

tells adb to talk to a specific device

Parameters
adbChan SocketChannel: the socket connection to adb
deviceSerialNumber String: the serial of the device to talk to, if null the default device selected is the device picked by adb.
Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
in case of I/O error on the connection.

write

public static void write (SocketChannel chan, 
                byte[] data, 
                int length, 
                int timeout)

Write until all data in "data" is written, the optional length is reached, the timeout expires, or the connection fails. Returns "true" if all data was written.

Parameters
chan SocketChannel: the opened socket to write to.
data byte: the buffer to send.
length int: the length to write or -1 to send the whole buffer.
timeout int: The timeout value. A timeout of zero means "wait forever".
Throws
TimeoutException in case of timeout on the connection.
in case of I/O error on the connection.

write

public static void write (SocketChannel chan, 
                byte[] data)

Write until all data in "data" is written or the connection fails or times out.

This uses the default time out value.

Parameters
chan SocketChannel: the opened socket to write to.
data byte: the buffer to send.
Throws
TimeoutException in case of timeout on the connection.
in case of I/O error on the connection.