com.android.ddmlib
Interface IDevice

public interface IDevice

A Device. It can be a physical device or an emulator.

Nested Class Summary

static class

IDevice.DeviceState The state of a device.

Field Summary

static int	CHANGE_BUILD_INFO Device change bit mask: build info change.
static int	CHANGE_CLIENT_LIST Device change bit mask: Client list change.
static int	CHANGE_STATE Device change bit mask: IDevice.DeviceState change.
static String	FIRST_EMULATOR_SN Serial number of the first connected emulator.
static String	MNT_DATA
static String	MNT_EXTERNAL_STORAGE
static String	MNT_ROOT
static String	PROP_BUILD_API_LEVEL
static String	PROP_BUILD_CODENAME
static String	PROP_BUILD_VERSION
static String	PROP_BUILD_VERSION_NUMBER Deprecated. Use PROP_BUILD_API_LEVEL.
static String	PROP_DEBUGGABLE

Method Summary

boolean	arePropertiesSet() Returns true> if properties have been cached
void	createForward(int localPort, int remotePort) Creates a port forwarding between a local and a remote port.
void	executeShellCommand(String command, IShellOutputReceiver receiver) Executes a shell command on the device, and sends the result to a receiver This is similar to calling executeShellCommand(command, receiver, DdmPreferences.getTimeOut()).
void	executeShellCommand(String command, IShellOutputReceiver receiver, int maxTimeToOutputResponse) Executes a shell command on the device, and sends the result to a receiver.
String	getAvdName() Returns the name of the AVD the emulator is running.
Integer	getBatteryLevel() Return the device's battery level, from 0 to 100 percent.
Integer	getBatteryLevel(long freshnessMs) Return the device's battery level, from 0 to 100 percent.
Client	getClient(String applicationName) Returns a Client by its application name.
String	getClientName(int pid) Returns the name of the client by pid or null if pid is unknown
Client[]	getClients() Returns the array of clients.
FileListingService	getFileListingService() Returns a FileListingService for this device.
String	getMountPoint(String name) Returns a mount point.
Map<String,String>	getProperties() Returns the device properties.
String	getProperty(String name) Returns the cached property value.
String	getPropertyCacheOrSync(String name) A combination of getProperty(String) and getPropertySync(String) that will attempt to retrieve the property from cache if available, and if not, will query the device directly.
int	getPropertyCount() Returns the number of property for this device.
String	getPropertySync(String name) A variant of getProperty(String) that will attempt to retrieve the given property from device directly, without using cache.
RawImage	getScreenshot() Takes a screen shot of the device and returns it as a RawImage.
String	getSerialNumber() Returns the serial number of the device.
IDevice.DeviceState	getState() Returns the state of the device.
SyncService	getSyncService() Returns a SyncService object to push / pull files to and from the device.
boolean	hasClients() Returns whether the Device has Clients.
String	installPackage(String packageFilePath, boolean reinstall, String... extraArgs) Installs an Android application on device.
String	installRemotePackage(String remoteFilePath, boolean reinstall, String... extraArgs) Installs the application package that was pushed to a temporary location on the device.
boolean	isBootLoader() Returns if the device is in bootloader mode.
boolean	isEmulator() Returns true if the device is an emulator.
boolean	isOffline() Returns if the device is offline.
boolean	isOnline() Returns if the device is ready.
void	pullFile(String remote, String local) Pulls a single file.
void	pushFile(String local, String remote) Push a single file.
void	reboot(String into) Reboot the device.
void	removeForward(int localPort, int remotePort) Removes a port forwarding between a local and a remote port.
void	removeRemotePackage(String remoteFilePath) Removes a file from device.
void	runEventLogService(LogReceiver receiver) Runs the event log service and outputs the event log to the LogReceiver.
void	runLogService(String logname, LogReceiver receiver) Runs the log service for the given log and outputs the log to the LogReceiver.
String	syncPackageToDevice(String localFilePath) Pushes a file to device
String	uninstallPackage(String packageName) Uninstalls an package from the device.

Field Detail

PROP_BUILD_VERSION

static final String PROP_BUILD_VERSION

See Also:

Constant Field Values

PROP_BUILD_API_LEVEL

static final String PROP_BUILD_API_LEVEL

See Also:

Constant Field Values

PROP_BUILD_CODENAME

static final String PROP_BUILD_CODENAME

See Also:

Constant Field Values

PROP_DEBUGGABLE

static final String PROP_DEBUGGABLE

See Also:

Constant Field Values

FIRST_EMULATOR_SN

static final String FIRST_EMULATOR_SN

Serial number of the first connected emulator.

See Also:

Constant Field Values

CHANGE_STATE

static final int CHANGE_STATE

Device change bit mask: IDevice.DeviceState change.

See Also:

Constant Field Values

CHANGE_CLIENT_LIST

static final int CHANGE_CLIENT_LIST

Device change bit mask: Client list change.

See Also:

Constant Field Values

CHANGE_BUILD_INFO

static final int CHANGE_BUILD_INFO

Device change bit mask: build info change.

See Also:

Constant Field Values

PROP_BUILD_VERSION_NUMBER

static final String PROP_BUILD_VERSION_NUMBER

Deprecated. Use PROP_BUILD_API_LEVEL.

See Also:

Constant Field Values

MNT_EXTERNAL_STORAGE

static final String MNT_EXTERNAL_STORAGE

See Also:

Constant Field Values

MNT_ROOT

static final String MNT_ROOT

See Also:

Constant Field Values

MNT_DATA

static final String MNT_DATA

See Also:

Constant Field Values

Method Detail

getSerialNumber

String getSerialNumber()

Returns the serial number of the device.

getAvdName

String getAvdName()

Returns the name of the AVD the emulator is running.

This is only valid if isEmulator() returns true.

If the emulator is not running any AVD (for instance it's running from an Android source tree build), this method will return "<build>".

Returns:

the name of the AVD or null if there isn't any.

getState

IDevice.DeviceState getState()

Returns the state of the device.

getProperties

Map<String,String> getProperties()

Returns the device properties. It contains the whole output of 'getprop'

getPropertyCount

int getPropertyCount()

Returns the number of property for this device.

getProperty

String getProperty(String name)

Returns the cached property value.

Parameters:

name - the name of the value to return.

Returns:

the value or null if the property does not exist or has not yet been cached.

arePropertiesSet

boolean arePropertiesSet()

Returns true> if properties have been cached

getPropertySync

String getPropertySync(String name)
                       throws TimeoutException,
                              AdbCommandRejectedException,
                              ShellCommandUnresponsiveException,
                              IOException

A variant of getProperty(String) that will attempt to retrieve the given property from device directly, without using cache.

Parameters:

name - the name of the value to return.

Returns:

the value or null if the property does not exist

Throws:

TimeoutException - in case of timeout on the connection.

AdbCommandRejectedException - if adb rejects the command

ShellCommandUnresponsiveException - in case the shell command doesn't send output for a given time.

IOException - in case of I/O error on the connection.

getPropertyCacheOrSync

String getPropertyCacheOrSync(String name)
                              throws TimeoutException,
                                     AdbCommandRejectedException,
                                     ShellCommandUnresponsiveException,
                                     IOException

A combination of getProperty(String) and getPropertySync(String) that will attempt to retrieve the property from cache if available, and if not, will query the device directly.

Parameters:

name - the name of the value to return.

Returns:

the value or null if the property does not exist

Throws:

TimeoutException - in case of timeout on the connection.

AdbCommandRejectedException - if adb rejects the command

ShellCommandUnresponsiveException - in case the shell command doesn't send output for a given time.

IOException - in case of I/O error on the connection.

getMountPoint

String getMountPoint(String name)

Returns a mount point.

Parameters:

name - the name of the mount point to return

See Also:

MNT_EXTERNAL_STORAGE, MNT_ROOT, MNT_DATA

isOnline

boolean isOnline()

Returns if the device is ready.

Returns:

true if getState() returns IDevice.DeviceState.ONLINE.

isEmulator

boolean isEmulator()

Returns true if the device is an emulator.

isOffline

boolean isOffline()

Returns if the device is offline.

Returns:

true if getState() returns IDevice.DeviceState.OFFLINE.

isBootLoader

boolean isBootLoader()

Returns if the device is in bootloader mode.

Returns:

true if getState() returns IDevice.DeviceState.BOOTLOADER.

hasClients

boolean hasClients()

Returns whether the Device has Clients.

getClients

Client[] getClients()

Returns the array of clients.

getClient

Client getClient(String applicationName)

Returns a Client by its application name.

Parameters:

applicationName - the name of the application

Returns:

the Client object or null if no match was found.

getSyncService

SyncService getSyncService()
                           throws TimeoutException,
                                  AdbCommandRejectedException,
                                  IOException

Returns a SyncService object to push / pull files to and from the device.

Returns:

null if the SyncService couldn't be created. This can happen if adb refuse to open the connection because the IDevice is invalid (or got disconnected).

Throws:

TimeoutException - in case of timeout on the connection.

AdbCommandRejectedException - if adb rejects the command

IOException - if the connection with adb failed.

getFileListingService

FileListingService getFileListingService()

Returns a FileListingService for this device.

getScreenshot

RawImage getScreenshot()
                       throws TimeoutException,
                              AdbCommandRejectedException,
                              IOException

Takes a screen shot of the device and returns it as a RawImage.

Returns:

the screenshot as a RawImage or null if something went wrong.

Throws:

TimeoutException - in case of timeout on the connection.

AdbCommandRejectedException - if adb rejects the command

IOException - in case of I/O error on the connection.

executeShellCommand

void executeShellCommand(String command,
                         IShellOutputReceiver receiver)
                         throws TimeoutException,
                                AdbCommandRejectedException,
                                ShellCommandUnresponsiveException,
                                IOException

Executes a shell command on the device, and sends the result to a receiver

This is similar to calling executeShellCommand(command, receiver, DdmPreferences.getTimeOut()).

Parameters:

command - the shell command to execute

receiver - the IShellOutputReceiver that will receives the output of the shell command

Throws:

TimeoutException - in case of timeout on the connection.

AdbCommandRejectedException - if adb rejects the command

ShellCommandUnresponsiveException - in case the shell command doesn't send output for a given time.

IOException - in case of I/O error on the connection.

See Also:

executeShellCommand(String, IShellOutputReceiver, int), DdmPreferences.getTimeOut()

executeShellCommand

void executeShellCommand(String command,
                         IShellOutputReceiver receiver,
                         int maxTimeToOutputResponse)
                         throws TimeoutException,
                                AdbCommandRejectedException,
                                ShellCommandUnresponsiveException,
                                IOException

Executes a shell command on the device, and sends the result to a receiver.

maxTimeToOutputResponse is used as a maximum waiting time when expecting the command output from the device.
At any time, if the shell command does not output anything for a period longer than maxTimeToOutputResponse, then the method will throw ShellCommandUnresponsiveException.

For commands like log output, a maxTimeToOutputResponse value of 0, meaning that the method will never throw and will block until the receiver's IShellOutputReceiver.isCancelled() returns true, should be used.

Parameters:

command - the shell command to execute

receiver - the IShellOutputReceiver that will receives the output of the shell command

maxTimeToOutputResponse - the maximum amount of time during which the command is allowed to not output any response. A value of 0 means the method will wait forever (until the receiver cancels the execution) for command output and never throw.

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.

IOException - in case of I/O error on the connection.

See Also:

DdmPreferences.getTimeOut()

runEventLogService

void runEventLogService(LogReceiver receiver)
                        throws TimeoutException,
                               AdbCommandRejectedException,
                               IOException

Runs the event log service and outputs the event log to the LogReceiver.

This call is blocking until LogReceiver.isCancelled() returns true.

Parameters:

receiver - the receiver to receive the event log entries.

Throws:

TimeoutException - in case of timeout on the connection. This can only be thrown if the timeout happens during setup. Once logs start being received, no timeout will occur as it's not possible to detect a difference between no log and timeout.

AdbCommandRejectedException - if adb rejects the command

IOException - in case of I/O error on the connection.

runLogService

void runLogService(String logname,
                   LogReceiver receiver)
                   throws TimeoutException,
                          AdbCommandRejectedException,
                          IOException

Runs the log service for the given log and outputs the log to the LogReceiver.

This call is blocking until LogReceiver.isCancelled() returns true.

Parameters:

logname - the logname of the log to read from.

receiver - the receiver to receive the event log entries.

Throws:

TimeoutException - in case of timeout on the connection. This can only be thrown if the timeout happens during setup. Once logs start being received, no timeout will occur as it's not possible to detect a difference between no log and timeout.

AdbCommandRejectedException - if adb rejects the command

IOException - in case of I/O error on the connection.

createForward

void createForward(int localPort,
                   int remotePort)
                   throws TimeoutException,
                          AdbCommandRejectedException,
                          IOException

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

Parameters:

localPort - the local port to forward

remotePort - the remote port.

Throws:

TimeoutException - in case of timeout on the connection.

AdbCommandRejectedException - if adb rejects the command

IOException - in case of I/O error on the connection.

removeForward

void removeForward(int localPort,
                   int remotePort)
                   throws TimeoutException,
                          AdbCommandRejectedException,
                          IOException

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

Parameters:

localPort - the local port to forward

remotePort - the remote port.

Throws:

TimeoutException - in case of timeout on the connection.

AdbCommandRejectedException - if adb rejects the command

IOException - in case of I/O error on the connection.

getClientName

String getClientName(int pid)

Returns the name of the client by pid or null if pid is unknown

Parameters:

pid - the pid of the client.

pushFile

void pushFile(String local,
              String remote)
              throws IOException,
                     AdbCommandRejectedException,
                     TimeoutException,
                     SyncException

Push a single file.

Parameters:

local - the local filepath.

remote - The remote filepath.

Throws:

IOException - in case of I/O error on the connection.

AdbCommandRejectedException - if adb rejects the command

TimeoutException - in case of a timeout reading responses from the device.

SyncException - if file could not be pushed

pullFile

void pullFile(String remote,
              String local)
              throws IOException,
                     AdbCommandRejectedException,
                     TimeoutException,
                     SyncException

Pulls a single file.

Parameters:

remote - the full path to the remote file

local - The local destination.

Throws:

IOException - in case of an IO exception.

AdbCommandRejectedException - if adb rejects the command

TimeoutException - in case of a timeout reading responses from the device.

SyncException - in case of a sync exception.

installPackage

String installPackage(String packageFilePath,
                      boolean reinstall,
                      String... extraArgs)
                      throws InstallException

Installs an Android application on device. This is a helper method that combines the syncPackageToDevice, installRemotePackage, and removePackage steps

Parameters:

packageFilePath - the absolute file system path to file on local host to install

reinstall - set to true if re-install of app should be performed

extraArgs - optional extra arguments to pass. See 'adb shell pm install --help' for available options.

Returns:

a String with an error code, or null if success.

Throws:

InstallException - if the installation fails.

syncPackageToDevice

String syncPackageToDevice(String localFilePath)
                           throws TimeoutException,
                                  AdbCommandRejectedException,
                                  IOException,
                                  SyncException

Pushes a file to device

Parameters:

localFilePath - the absolute path to file on local host

Returns:

String destination path on device for file

Throws:

TimeoutException - in case of timeout on the connection.

AdbCommandRejectedException - if adb rejects the command

IOException - in case of I/O error on the connection.

SyncException - if an error happens during the push of the package on the device.

installRemotePackage

String installRemotePackage(String remoteFilePath,
                            boolean reinstall,
                            String... extraArgs)
                            throws InstallException

Installs the application package that was pushed to a temporary location on the device.

Parameters:

remoteFilePath - absolute file path to package file on device

reinstall - set to true if re-install of app should be performed

extraArgs - optional extra arguments to pass. See 'adb shell pm install --help' for available options.

Throws:

InstallException - if the installation fails.

removeRemotePackage

void removeRemotePackage(String remoteFilePath)
                         throws InstallException

Removes a file from device.

Parameters:

remoteFilePath - path on device of file to remove

Throws:

InstallException - if the installation fails.

uninstallPackage

String uninstallPackage(String packageName)
                        throws InstallException

Uninstalls an package from the device.

Parameters:

packageName - the Android application package name to uninstall

Returns:

a String with an error code, or null if success.

Throws:

InstallException - if the uninstallation fails.

reboot

void reboot(String into)
            throws TimeoutException,
                   AdbCommandRejectedException,
                   IOException

Reboot the device.

Parameters:

into - the bootloader name to reboot into, or null to just reboot the device.

Throws:

TimeoutException - in case of timeout on the connection.

AdbCommandRejectedException - if adb rejects the command

IOException

getBatteryLevel

Integer getBatteryLevel()
                        throws TimeoutException,
                               AdbCommandRejectedException,
                               IOException,
                               ShellCommandUnresponsiveException

Return the device's battery level, from 0 to 100 percent.

The battery level may be cached. Only queries the device for its battery level if 5 minutes have expired since the last successful query.

Returns:

the battery level or null if it could not be retrieved

Throws:

TimeoutException

AdbCommandRejectedException

IOException

ShellCommandUnresponsiveException

getBatteryLevel

Integer getBatteryLevel(long freshnessMs)
                        throws TimeoutException,
                               AdbCommandRejectedException,
                               IOException,
                               ShellCommandUnresponsiveException

Return the device's battery level, from 0 to 100 percent.

The battery level may be cached. Only queries the device for its battery level if freshnessMs ms have expired since the last successful query.

Parameters:

freshnessMs -

Returns:

the battery level or null if it could not be retrieved

Throws:

ShellCommandUnresponsiveException

TimeoutException

AdbCommandRejectedException

IOException