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 java.lang.String	FIRST_EMULATOR_SN Serial number of the first connected emulator.
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 java.lang.String	MNT_DATA
static java.lang.String	MNT_EXTERNAL_STORAGE
static java.lang.String	MNT_ROOT
static java.lang.String	PROP_BUILD_API_LEVEL
static java.lang.String	PROP_BUILD_CODENAME
static java.lang.String	PROP_BUILD_VERSION
static java.lang.String	PROP_BUILD_VERSION_NUMBER Deprecated. Use PROP_BUILD_API_LEVEL.
static java.lang.String	PROP_DEBUGGABLE

Method Summary

void	createForward(int localPort, int remotePort) Creates a port forwarding between a local and a remote port.
void	executeShellCommand(java.lang.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(java.lang.String command, IShellOutputReceiver receiver, int maxTimeToOutputResponse) Executes a shell command on the device, and sends the result to a receiver.
java.lang.String	getAvdName() Returns the name of the AVD the emulator is running.
Client	getClient(java.lang.String applicationName) Returns a Client by its application name.
java.lang.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.
java.lang.String	getMountPoint(java.lang.String name) Returns a mount point.
java.util.Map<java.lang.String,java.lang.String>	getProperties() Returns the device properties.
java.lang.String	getProperty(java.lang.String name) Returns a property value.
int	getPropertyCount() Returns the number of property for this device.
RawImage	getScreenshot() Takes a screen shot of the device and returns it as a RawImage.
java.lang.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.
java.lang.String	installPackage(java.lang.String packageFilePath, boolean reinstall) Installs an Android application on device.
java.lang.String	installRemotePackage(java.lang.String remoteFilePath, boolean reinstall) 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	reboot(java.lang.String into) Reboot the device.
void	removeForward(int localPort, int remotePort) Removes a port forwarding between a local and a remote port.
void	removeRemotePackage(java.lang.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(java.lang.String logname, LogReceiver receiver) Runs the log service for the given log and outputs the log to the LogReceiver.
java.lang.String	syncPackageToDevice(java.lang.String localFilePath) Pushes a file to device
java.lang.String	uninstallPackage(java.lang.String packageName) Uninstalls an package from the device.

Field Detail

PROP_BUILD_VERSION

static final java.lang.String PROP_BUILD_VERSION

See Also:

Constant Field Values

PROP_BUILD_API_LEVEL

static final java.lang.String PROP_BUILD_API_LEVEL

See Also:

Constant Field Values

PROP_BUILD_CODENAME

static final java.lang.String PROP_BUILD_CODENAME

See Also:

Constant Field Values

PROP_DEBUGGABLE

static final java.lang.String PROP_DEBUGGABLE

See Also:

Constant Field Values

FIRST_EMULATOR_SN

static final java.lang.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 java.lang.String PROP_BUILD_VERSION_NUMBER

Deprecated. Use PROP_BUILD_API_LEVEL.

See Also:

Constant Field Values

MNT_EXTERNAL_STORAGE

static final java.lang.String MNT_EXTERNAL_STORAGE

See Also:

Constant Field Values

MNT_ROOT

static final java.lang.String MNT_ROOT

See Also:

Constant Field Values

MNT_DATA

static final java.lang.String MNT_DATA

See Also:

Constant Field Values

Method Detail

getSerialNumber

java.lang.String getSerialNumber()

Returns the serial number of the device.

getAvdName

java.lang.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

java.util.Map<java.lang.String,java.lang.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

java.lang.String getProperty(java.lang.String name)

Returns a property value.

Parameters:

name - the name of the value to return.

Returns:

the value or null if the property does not exist.

getMountPoint

java.lang.String getMountPoint(java.lang.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(java.lang.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,
                                  java.io.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

java.io.IOException - if the connection with adb failed.

getFileListingService

FileListingService getFileListingService()

Returns a FileListingService for this device.

getScreenshot

RawImage getScreenshot()
                       throws TimeoutException,
                              AdbCommandRejectedException,
                              java.io.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

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

executeShellCommand

void executeShellCommand(java.lang.String command,
                         IShellOutputReceiver receiver)
                         throws TimeoutException,
                                AdbCommandRejectedException,
                                ShellCommandUnresponsiveException,
                                java.io.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.

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

See Also:

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

executeShellCommand

void executeShellCommand(java.lang.String command,
                         IShellOutputReceiver receiver,
                         int maxTimeToOutputResponse)
                         throws TimeoutException,
                                AdbCommandRejectedException,
                                ShellCommandUnresponsiveException,
                                java.io.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.

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

See Also:

DdmPreferences.getTimeOut()

runEventLogService

void runEventLogService(LogReceiver receiver)
                        throws TimeoutException,
                               AdbCommandRejectedException,
                               java.io.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

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

runLogService

void runLogService(java.lang.String logname,
                   LogReceiver receiver)
                   throws TimeoutException,
                          AdbCommandRejectedException,
                          java.io.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

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

createForward

void createForward(int localPort,
                   int remotePort)
                   throws TimeoutException,
                          AdbCommandRejectedException,
                          java.io.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

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

removeForward

void removeForward(int localPort,
                   int remotePort)
                   throws TimeoutException,
                          AdbCommandRejectedException,
                          java.io.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

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

getClientName

java.lang.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.

installPackage

java.lang.String installPackage(java.lang.String packageFilePath,
                                boolean reinstall)
                                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

Returns:

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

Throws:

InstallException - if the installation fails.

syncPackageToDevice

java.lang.String syncPackageToDevice(java.lang.String localFilePath)
                                     throws TimeoutException,
                                            AdbCommandRejectedException,
                                            java.io.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

java.io.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

java.lang.String installRemotePackage(java.lang.String remoteFilePath,
                                      boolean reinstall)
                                      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

Throws:

InstallException - if the installation fails.

removeRemotePackage

void removeRemotePackage(java.lang.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

java.lang.String uninstallPackage(java.lang.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(java.lang.String into)
            throws TimeoutException,
                   AdbCommandRejectedException,
                   java.io.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

java.io.IOException