com.android.ddmlib
Interface IDevice

All Superinterfaces:

IShellEnabledDevice

public interface IDevice
extends IShellEnabledDevice

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

Nested Class Summary

static class	IDevice.DeviceState The state of a device.
static class	IDevice.DeviceUnixSocketNamespace Namespace of a Unix Domain Socket created on the device.
static class	IDevice.Feature Device level software features.
static class	IDevice.HardwareFeature Device level hardware features.

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 java.lang.String	FIRST_EMULATOR_SN Serial number of the first connected emulator.
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_CHARACTERISTICS
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
static java.lang.String	PROP_DEVICE_CPU_ABI
static java.lang.String	PROP_DEVICE_CPU_ABI2
static java.lang.String	PROP_DEVICE_MANUFACTURER
static java.lang.String	PROP_DEVICE_MODEL

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	createForward(int localPort, java.lang.String remoteSocketName, IDevice.DeviceUnixSocketNamespace namespace) Creates a port forwarding between a local TCP port and a remote Unix Domain Socket.
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) Deprecated. Use IShellEnabledDevice.executeShellCommand(String, IShellOutputReceiver, long, java.util.concurrent.TimeUnit).
java.lang.String	getAvdName() Returns the name of the AVD the emulator is running.
java.lang.Integer	getBatteryLevel() Return the device's battery level, from 0 to 100 percent.
java.lang.Integer	getBatteryLevel(long freshnessMs) Return the device's battery level, from 0 to 100 percent.
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 the cached property value.
java.lang.String	getPropertyCacheOrSync(java.lang.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.
java.lang.String	getPropertySync(java.lang.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.
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, java.lang.String... extraArgs) Installs an Android application on device.
java.lang.String	installRemotePackage(java.lang.String remoteFilePath, boolean reinstall, java.lang.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(java.lang.String remote, java.lang.String local) Pulls a single file.
void	pushFile(java.lang.String local, java.lang.String remote) Push a single file.
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	removeForward(int localPort, java.lang.String remoteSocketName, IDevice.DeviceUnixSocketNamespace namespace) Removes an existing 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.
void	startScreenRecorder(java.lang.String remoteFilePath, ScreenRecorderOptions options, IShellOutputReceiver receiver) Initiates screen recording on the device if the device supports IDevice.Feature.SCREEN_RECORD.
boolean	supportsFeature(IDevice.Feature feature) Returns whether this device supports the given software feature.
boolean	supportsFeature(IDevice.HardwareFeature feature) Returns whether this device supports the given hardware feature.
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.

Methods inherited from interface com.android.ddmlib.IShellEnabledDevice

executeShellCommand, getName

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_DEVICE_MODEL

static final java.lang.String PROP_DEVICE_MODEL

See Also:

Constant Field Values

PROP_DEVICE_MANUFACTURER

static final java.lang.String PROP_DEVICE_MANUFACTURER

See Also:

Constant Field Values

PROP_DEVICE_CPU_ABI

static final java.lang.String PROP_DEVICE_CPU_ABI

See Also:

Constant Field Values

PROP_DEVICE_CPU_ABI2

static final java.lang.String PROP_DEVICE_CPU_ABI2

See Also:

Constant Field Values

PROP_BUILD_CHARACTERISTICS

static final java.lang.String PROP_BUILD_CHARACTERISTICS

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

@Deprecated
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

@NonNull
java.lang.String getSerialNumber()

Returns the serial number of the device.

getAvdName

@Nullable
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 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

java.lang.String getPropertySync(java.lang.String name)
                                 throws TimeoutException,
                                        AdbCommandRejectedException,
                                        ShellCommandUnresponsiveException,
                                        java.io.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.

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

getPropertyCacheOrSync

java.lang.String getPropertyCacheOrSync(java.lang.String name)
                                        throws TimeoutException,
                                               AdbCommandRejectedException,
                                               ShellCommandUnresponsiveException,
                                               java.io.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.

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

supportsFeature

boolean supportsFeature(@NonNull
                        IDevice.Feature feature)

Returns whether this device supports the given software feature.

supportsFeature

boolean supportsFeature(@NonNull
                        IDevice.HardwareFeature feature)

Returns whether this device supports the given hardware feature.

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.

startScreenRecorder

void startScreenRecorder(@NonNull
                         java.lang.String remoteFilePath,
                         @NonNull
                         ScreenRecorderOptions options,
                         @NonNull
                         IShellOutputReceiver receiver)
                         throws TimeoutException,
                                AdbCommandRejectedException,
                                java.io.IOException,
                                ShellCommandUnresponsiveException

Initiates screen recording on the device if the device supports IDevice.Feature.SCREEN_RECORD.

Throws:

TimeoutException

AdbCommandRejectedException

java.io.IOException

ShellCommandUnresponsiveException

executeShellCommand

@Deprecated
void executeShellCommand(java.lang.String command,
                                    IShellOutputReceiver receiver,
                                    int maxTimeToOutputResponse)
                         throws TimeoutException,
                                AdbCommandRejectedException,
                                ShellCommandUnresponsiveException,
                                java.io.IOException

Deprecated. Use IShellEnabledDevice.executeShellCommand(String, IShellOutputReceiver, long, java.util.concurrent.TimeUnit).

Throws:

TimeoutException

AdbCommandRejectedException

ShellCommandUnresponsiveException

java.io.IOException

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()

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.

createForward

void createForward(int localPort,
                   java.lang.String remoteSocketName,
                   IDevice.DeviceUnixSocketNamespace namespace)
                   throws TimeoutException,
                          AdbCommandRejectedException,
                          java.io.IOException

Creates a port forwarding between a local TCP port and a remote Unix Domain Socket.

Parameters:

localPort - the local port to forward

remoteSocketName - name of the unix domain socket created on the device

namespace - namespace in which the unix domain socket was created

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.

removeForward

void removeForward(int localPort,
                   java.lang.String remoteSocketName,
                   IDevice.DeviceUnixSocketNamespace namespace)
                   throws TimeoutException,
                          AdbCommandRejectedException,
                          java.io.IOException

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

Parameters:

localPort - the local port to forward

remoteSocketName - the remote unix domain socket name.

namespace - namespace in which the unix domain socket was created

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.

pushFile

void pushFile(java.lang.String local,
              java.lang.String remote)
              throws java.io.IOException,
                     AdbCommandRejectedException,
                     TimeoutException,
                     SyncException

Push a single file.

Parameters:

local - the local filepath.

remote - The remote filepath.

Throws:

java.io.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(java.lang.String remote,
              java.lang.String local)
              throws java.io.IOException,
                     AdbCommandRejectedException,
                     TimeoutException,
                     SyncException

Pulls a single file.

Parameters:

remote - the full path to the remote file

local - The local destination.

Throws:

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

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

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

getBatteryLevel

java.lang.Integer getBatteryLevel()
                                  throws TimeoutException,
                                         AdbCommandRejectedException,
                                         java.io.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

java.io.IOException

ShellCommandUnresponsiveException

getBatteryLevel

java.lang.Integer getBatteryLevel(long freshnessMs)
                                  throws TimeoutException,
                                         AdbCommandRejectedException,
                                         java.io.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

java.io.IOException