IDevice

public interface IDevice
implements IShellEnabledDevice

com.android.ddmlib.IDevice

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

Summary

Constants

int CHANGE_BUILD_INFO

Device change bit mask: build info change.

int CHANGE_CLIENT_LIST

Device change bit mask: Client list change.

int CHANGE_PROFILEABLE_CLIENT_LIST

Device change bit mask: ProfileableClient list change.

int CHANGE_STATE

Device change bit mask: DeviceState change.

String FIRST_EMULATOR_SN

Serial number of the first connected emulator.

String MNT_DATA

String MNT_EXTERNAL_STORAGE

String MNT_ROOT

String PROP_BUILD_API_LEVEL

String PROP_BUILD_CHARACTERISTICS

String PROP_BUILD_CODENAME

String PROP_BUILD_TAGS

String PROP_BUILD_TYPE

String PROP_BUILD_VERSION

String PROP_BUILD_VERSION_NUMBER

This constant is deprecated. Use PROP_BUILD_API_LEVEL.

String PROP_DEBUGGABLE

String PROP_DEVICE_CPU_ABI

String PROP_DEVICE_CPU_ABI2

String PROP_DEVICE_CPU_ABI_LIST

String PROP_DEVICE_DENSITY

String PROP_DEVICE_EMULATOR_DENSITY

String PROP_DEVICE_LANGUAGE

String PROP_DEVICE_MANUFACTURER

String PROP_DEVICE_MODEL

String PROP_DEVICE_REGION

String RE_EMULATOR_SN

Emulator Serial Number regexp.

String UNKNOWN_PACKAGE

Public methods

abstract boolean arePropertiesSet()

Returns true if properties have been cached

abstract void createForward(int localPort, String remoteSocketName, IDevice.DeviceUnixSocketNamespace namespace)

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

abstract void createForward(int localPort, int remotePort)

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

default void createReverse(int remotePort, int localPort)

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

default void executeBinderCommand(String[] parameters, IShellOutputReceiver receiver, long maxTimeToOutputResponse, TimeUnit maxTimeUnits, InputStream is)

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

This uses exec:cmd call or faster abb_exec: if both device OS and host ADB server support Android Binder Bridge execute feature.

default void executeShellCommand(String command, IShellOutputReceiver receiver, long maxTimeToOutputResponse, TimeUnit maxTimeUnits, InputStream is)

A version of executeShell command that can take an input stream to send through stdin.

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

abstract void executeShellCommand(String command, IShellOutputReceiver receiver, int maxTimeToOutputResponse)

This method is deprecated. Use IShellEnabledDevice.executeShellCommand(String, com.android.ddmlib.IShellOutputReceiver, long, TimeUnit).

default void forceStop(String applicationName)

Force stop an application by its application name.

abstract getAbis()

Returns the ABIs supported by this device.

default ListenableFuture<AvdData> getAvdData()

Returns information about the AVD the emulator is running.

abstract String getAvdName()

Returns the name of the AVD the emulator is running.

abstract String getAvdPath()

Returns the absolute path to the virtual device in the file system.

abstract getBattery(long freshnessTime, TimeUnit timeUnit)

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

abstract getBattery()

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

abstract Integer getBatteryLevel(long freshnessMs)

This method is deprecated. use getBattery(long, TimeUnit)

abstract Integer getBatteryLevel()

This method is deprecated. use getBattery()

abstract Client getClient(String applicationName)

Returns a Client by its application name.

abstract String getClientName(int pid)

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

abstract Client[] getClients()

Returns the array of clients.

abstract int getDensity()

Returns the density bucket of the device screen by reading the value for system property PROP_DEVICE_DENSITY.

abstract FileListingService getFileListingService()

Returns a FileListingService for this device.

default getHardwareCharacteristics()

Returns features obtained by reading the build characteristics property.

abstract String getLanguage()

Returns the user's language.

default InstallMetrics getLastInstallMetrics()

Gets the information about the most recent installation on this device.

abstract String getMountPoint(String name)

Returns a mount point.

default ProfileableClient[] getProfileableClients()

Returns the array of profileable clients.

abstract getProperties()

This method is deprecated. use IShellEnabledDevice.getSystemProperty(String) instead

abstract String getProperty(String name)

Convenience method that attempts to retrieve a property via IShellEnabledDevice.getSystemProperty(String) with a very short wait time, and swallows exceptions.

abstract String getPropertyCacheOrSync(String name)

This method is deprecated. use IShellEnabledDevice.getSystemProperty(String) instead

abstract int getPropertyCount()

This method is deprecated. implementation detail

abstract String getPropertySync(String name)

This method is deprecated. use IShellEnabledDevice.getSystemProperty(String)

abstract String getRegion()

Returns the user's region.

abstract RawImage getScreenshot()

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

abstract RawImage getScreenshot(long timeout, TimeUnit unit)
abstract String getSerialNumber()

Returns the serial number of the device.

abstract IDevice.DeviceState getState()

Returns the state of the device.

abstract SyncService getSyncService()

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

abstract boolean hasClients()

Returns whether the IDevice has Clients.

abstract void installPackage(String packageFilePath, boolean reinstall, InstallReceiver receiver, long maxTimeout, long maxTimeToOutputResponse, TimeUnit maxTimeUnits, String... extraArgs)

Installs an Android application on device.

abstract void installPackage(String packageFilePath, boolean reinstall, InstallReceiver receiver, String... extraArgs)

Installs an Android application on device.

abstract void installPackage(String packageFilePath, boolean reinstall, String... extraArgs)

Installs an Android application on device.

default void installPackages( apks, boolean reinstall, installOptions)

Installs an Android application made of several APK files (one main and 0..n split packages) with default timeout

abstract void installPackages( apks, boolean reinstall, installOptions, long timeout, TimeUnit timeoutUnit)

Installs an Android application made of several APK files (one main and 0..n split packages)

abstract void installRemotePackage(String remoteFilePath, boolean reinstall, InstallReceiver receiver, String... extraArgs)

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

abstract void installRemotePackage(String remoteFilePath, boolean reinstall, String... extraArgs)

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

abstract void installRemotePackage(String remoteFilePath, boolean reinstall, InstallReceiver receiver, long maxTimeout, long maxTimeToOutputResponse, TimeUnit maxTimeUnits, String... extraArgs)

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

default void installRemotePackages( remoteApks, boolean reinstall, installOptions)

Installs an Android application made of several APK files sitting locally on the device with default timeout

default void installRemotePackages( remoteApks, boolean reinstall, installOptions, long timeout, TimeUnit timeoutUnit)

Installs an Android application made of several APK files sitting locally on the device

abstract boolean isBootLoader()

Returns if the device is in bootloader mode.

abstract boolean isEmulator()

Returns true if the device is an emulator.

abstract boolean isOffline()

Returns if the device is offline.

abstract boolean isOnline()

Returns if the device is ready.

abstract boolean isRoot()

Queries the current root-status of the device.

default void kill(String applicationName)

Kills an application by its application name.

abstract void pullFile(String remote, String local)

Pulls a single file.

default void push(String[] local, String remote)

Pushes several files or directories.

abstract void pushFile(String local, String remote)

Pushes a single file.

default SocketChannel rawBinder(String service, String[] parameters)

Invoke the Android Binder Bridge service on a remote device.

default SocketChannel rawExec(String executable, String[] parameters)

Invoke the host:exec service on a remote device.

abstract void reboot(String into)

Reboot the device.

default void removeForward(int localPort)

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

default void removeForward(int localPort, int remotePort)

This method is deprecated. Use removeForward(int)

default void removeForward(int localPort, String remoteSocketName, IDevice.DeviceUnixSocketNamespace namespace)

This method is deprecated. Use removeForward(int)

abstract void removeRemotePackage(String remoteFilePath)

Removes a file from device.

default void removeReverse(int remotePort)

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

abstract boolean root()

Ask the adb daemon to become root on the device.

abstract void startScreenRecorder(String remoteFilePath, ScreenRecorderOptions options, IShellOutputReceiver receiver)

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

abstract boolean supportsFeature(IDevice.HardwareFeature feature)

Returns whether this device supports the given hardware feature.

abstract boolean supportsFeature(IDevice.Feature feature)

Returns whether this device supports the given software feature.

abstract String syncPackageToDevice(String localFilePath)

Pushes a file to device

abstract String uninstallApp(String applicationID, String... extraArgs)

Uninstalls an app from the device.

abstract String uninstallPackage(String packageName)

Uninstalls a package from the device.

Constants

CHANGE_BUILD_INFO

public static final int CHANGE_BUILD_INFO

Device change bit mask: build info change.

Constant Value: 4 (0x00000004)

CHANGE_CLIENT_LIST

public static final int CHANGE_CLIENT_LIST

Device change bit mask: Client list change.

Constant Value: 2 (0x00000002)

CHANGE_PROFILEABLE_CLIENT_LIST

public static final int CHANGE_PROFILEABLE_CLIENT_LIST

Device change bit mask: ProfileableClient list change.

Constant Value: 8 (0x00000008)

CHANGE_STATE

public static final int CHANGE_STATE

Device change bit mask: DeviceState change.

Constant Value: 1 (0x00000001)

FIRST_EMULATOR_SN

public static final String FIRST_EMULATOR_SN

Serial number of the first connected emulator.

Constant Value: "emulator-5554"

MNT_DATA

public static final String MNT_DATA

Constant Value: "ANDROID_DATA"

MNT_EXTERNAL_STORAGE

public static final String MNT_EXTERNAL_STORAGE

Constant Value: "EXTERNAL_STORAGE"

MNT_ROOT

public static final String MNT_ROOT

Constant Value: "ANDROID_ROOT"

PROP_BUILD_API_LEVEL

public static final String PROP_BUILD_API_LEVEL

Constant Value: "ro.build.version.sdk"

PROP_BUILD_CHARACTERISTICS

public static final String PROP_BUILD_CHARACTERISTICS

Constant Value: "ro.build.characteristics"

PROP_BUILD_CODENAME

public static final String PROP_BUILD_CODENAME

Constant Value: "ro.build.version.codename"

PROP_BUILD_TAGS

public static final String PROP_BUILD_TAGS

Constant Value: "ro.build.tags"

PROP_BUILD_TYPE

public static final String PROP_BUILD_TYPE

Constant Value: "ro.build.type"

PROP_BUILD_VERSION

public static final String PROP_BUILD_VERSION

Constant Value: "ro.build.version.release"

PROP_BUILD_VERSION_NUMBER

public static final String PROP_BUILD_VERSION_NUMBER

This constant is deprecated.
Use PROP_BUILD_API_LEVEL.

Constant Value: "ro.build.version.sdk"

PROP_DEBUGGABLE

public static final String PROP_DEBUGGABLE

Constant Value: "ro.debuggable"

PROP_DEVICE_CPU_ABI

public static final String PROP_DEVICE_CPU_ABI

Constant Value: "ro.product.cpu.abi"

PROP_DEVICE_CPU_ABI2

public static final String PROP_DEVICE_CPU_ABI2

Constant Value: "ro.product.cpu.abi2"

PROP_DEVICE_CPU_ABI_LIST

public static final String PROP_DEVICE_CPU_ABI_LIST

Constant Value: "ro.product.cpu.abilist"

PROP_DEVICE_DENSITY

public static final String PROP_DEVICE_DENSITY

Constant Value: "ro.sf.lcd_density"

PROP_DEVICE_EMULATOR_DENSITY

public static final String PROP_DEVICE_EMULATOR_DENSITY

Constant Value: "qemu.sf.lcd_density"

PROP_DEVICE_LANGUAGE

public static final String PROP_DEVICE_LANGUAGE

Constant Value: "persist.sys.language"

PROP_DEVICE_MANUFACTURER

public static final String PROP_DEVICE_MANUFACTURER

Constant Value: "ro.product.manufacturer"

PROP_DEVICE_MODEL

public static final String PROP_DEVICE_MODEL

Constant Value: "ro.product.model"

PROP_DEVICE_REGION

public static final String PROP_DEVICE_REGION

Constant Value: "persist.sys.country"

RE_EMULATOR_SN

public static final String RE_EMULATOR_SN

Emulator Serial Number regexp.

Constant Value: "emulator-(\d+)"

UNKNOWN_PACKAGE

public static final String UNKNOWN_PACKAGE

Constant Value: ""

Public methods

arePropertiesSet

public abstract boolean arePropertiesSet ()

Returns true if properties have been cached

Returns
boolean

createForward

public abstract void createForward (int localPort, 
                String remoteSocketName, 
                IDevice.DeviceUnixSocketNamespace namespace)

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

Parameters
localPort int: the local port to forward
remoteSocketName String: name of the unix domain socket created on the device
namespace IDevice.DeviceUnixSocketNamespace: namespace in which the unix domain socket was created
Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
in case of I/O error on the connection.

createForward

public abstract void createForward (int localPort, 
                int remotePort)

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

Parameters
localPort int: the local port to forward
remotePort int: the remote port.
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 void createReverse (int remotePort, 
                int localPort)

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

Parameters
remotePort int: the remote port to reverse.
localPort int: the local port
Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
in case of I/O error on the connection.

executeBinderCommand

public void executeBinderCommand (String[] parameters, 
                IShellOutputReceiver receiver, 
                long maxTimeToOutputResponse, 
                TimeUnit maxTimeUnits, 
                InputStream is)

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

This uses exec:cmd call or faster abb_exec: if both device OS and host ADB server support Android Binder Bridge execute feature.

Parameters
parameters String: the binder command to execute
receiver IShellOutputReceiver: the IShellOutputReceiver that will receives the output of the binder command
maxTimeToOutputResponse long

maxTimeUnits TimeUnit

is InputStream: optional input stream to send through stdin
Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
ShellCommandUnresponsiveException in case the binder command doesn't send output for a given time.
in case of I/O error on the connection.

executeShellCommand

public void executeShellCommand (String command, 
                IShellOutputReceiver receiver, 
                long maxTimeToOutputResponse, 
                TimeUnit maxTimeUnits, 
                InputStream is)

A version of executeShell command that can take an input stream to send through stdin.

Parameters
command String

receiver IShellOutputReceiver

maxTimeToOutputResponse long

maxTimeUnits TimeUnit

is InputStream

Throws
AdbCommandRejectedException
ShellCommandUnresponsiveException
TimeoutException

executeShellCommand

public abstract 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()).

Parameters
command String: the shell command to execute
receiver IShellOutputReceiver: 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.
in case of I/O error on the connection.

executeShellCommand

public abstract void executeShellCommand (String command, 
                IShellOutputReceiver receiver, 
                int maxTimeToOutputResponse)

This method is deprecated.
Use IShellEnabledDevice.executeShellCommand(String, com.android.ddmlib.IShellOutputReceiver, long, TimeUnit).

Parameters
command String

receiver IShellOutputReceiver

maxTimeToOutputResponse int

Throws
AdbCommandRejectedException
ShellCommandUnresponsiveException
TimeoutException

forceStop

public void forceStop (String applicationName)

Force stop an application by its application name. This removes all pending alarms and queued computation.

Parameters
applicationName String: the name of the application

getAbis

public abstract  getAbis ()

Returns the ABIs supported by this device. The ABIs are sorted in preferred order, with the first ABI being the most preferred.

Returns
the list of ABIs.

getAvdData

public ListenableFuture<AvdData> getAvdData ()

Returns information about the AVD the emulator is running.

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

AvdData.getPath is the AVD path or null if this is a physical device, the emulator console subcommand failed, or the emulator's version is older than 30.0.18

Returns
ListenableFuture<AvdData> the AvdData for the device.

getAvdName

public abstract 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>".

Note: Prefer using getAvdData() if you want control over the timeout.

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

getAvdPath

public abstract String getAvdPath ()

Returns the absolute path to the virtual device in the file system. The path is operating system dependent; it will have / name separators on Linux and \ separators on Windows.

Note: Prefer using getAvdData() if you want control over the timeout.

Returns
String the AVD path or null if this is a physical device, the emulator console subcommand failed, or the emulator's version is older than 30.0.18

getBattery

public abstract  getBattery (long freshnessTime, 
                TimeUnit timeUnit)

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 freshnessTime has expired since the last successful query.

Parameters
freshnessTime long: the desired recency of battery level
timeUnit TimeUnit: the ERROR(/TimeUnit) of freshnessTime
Returns
a ERROR(/Future) that can be used to query the battery level. The Future will return a ERROR(/ExecutionException) if battery level could not be retrieved.

getBattery

public abstract  getBattery ()

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
a ERROR(/Future) that can be used to query the battery level. The Future will return a ERROR(/ExecutionException) if battery level could not be retrieved.

getBatteryLevel

public abstract Integer getBatteryLevel (long freshnessMs)

This method is deprecated.
use getBattery(long, TimeUnit)

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.

Returns
Integer the battery level or null if it could not be retrieved
Throws
com.android.ddmlib.ShellCommandUnresponsiveException
AdbCommandRejectedException
ShellCommandUnresponsiveException
TimeoutException

getBatteryLevel

public abstract Integer getBatteryLevel ()

This method is deprecated.
use getBattery()

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
Integer the battery level or null if it could not be retrieved
Throws
AdbCommandRejectedException
ShellCommandUnresponsiveException
TimeoutException

getClient

public abstract Client getClient (String applicationName)

Returns a Client by its application name.

Parameters
applicationName String: the name of the application
Returns
Client the Client object or null if no match was found.

getClientName

public abstract String getClientName (int pid)

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

Parameters
pid int: the pid of the client.
Returns
String

getClients

public abstract Client[] getClients ()

Returns the array of clients.

Returns
Client[]

getDensity

public abstract int getDensity ()

Returns the density bucket of the device screen by reading the value for system property PROP_DEVICE_DENSITY.

Returns
int the density, or -1 if it cannot be determined.

getFileListingService

public abstract FileListingService getFileListingService ()

Returns a FileListingService for this device.

Returns
FileListingService

getHardwareCharacteristics

public  getHardwareCharacteristics ()

Returns features obtained by reading the build characteristics property.

Returns

getLanguage

public abstract String getLanguage ()

Returns the user's language.

Returns
String the user's language, or null if it's unknown

getLastInstallMetrics

public InstallMetrics getLastInstallMetrics ()

Gets the information about the most recent installation on this device.

Returns
InstallMetrics InstallMetrics metrics describing the installation.

getMountPoint

public abstract String getMountPoint (String name)

Returns a mount point.

Parameters
name String: the name of the mount point to return
Returns
String

getProfileableClients

public ProfileableClient[] getProfileableClients ()

Returns the array of profileable clients.

Returns
ProfileableClient[]

getProperties

public abstract  getProperties ()

This method is deprecated.
use IShellEnabledDevice.getSystemProperty(String) instead

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

Returns

getProperty

public abstract String getProperty (String name)

Convenience method that attempts to retrieve a property via IShellEnabledDevice.getSystemProperty(String) with a very short wait time, and swallows exceptions.

Note: Prefer using IShellEnabledDevice.getSystemProperty(String) if you want control over the timeout.

Parameters
name String: the name of the value to return.
Returns
String the value or null if the property value was not immediately available

getPropertyCacheOrSync

public abstract String getPropertyCacheOrSync (String name)

This method is deprecated.
use IShellEnabledDevice.getSystemProperty(String) instead

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

Parameters
name String: the name of the value to return.
Returns
String 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.
in case of I/O error on the connection.

getPropertyCount

public abstract int getPropertyCount ()

This method is deprecated.
implementation detail

Returns the number of property for this device.

Returns
int

getPropertySync

public abstract String getPropertySync (String name)

This method is deprecated.
use IShellEnabledDevice.getSystemProperty(String)

A variant of getProperty(String) that will attempt to retrieve the given property from device directly, without using cache. This method should (only) be used for any volatile properties.

Parameters
name String: the name of the value to return.
Returns
String 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.
in case of I/O error on the connection.

getRegion

public abstract String getRegion ()

Returns the user's region.

Returns
String the user's region, or null if it's unknown

getScreenshot

public abstract RawImage getScreenshot ()

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

Returns
RawImage 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
in case of I/O error on the connection.

getScreenshot

public abstract RawImage getScreenshot (long timeout, 
                TimeUnit unit)

Parameters
timeout long

unit TimeUnit

Returns
RawImage

Throws
AdbCommandRejectedException
TimeoutException

getSerialNumber

public abstract String getSerialNumber ()

Returns the serial number of the device.

Returns
String

getState

public abstract IDevice.DeviceState getState ()

Returns the state of the device.

Returns
IDevice.DeviceState

getSyncService

public abstract SyncService getSyncService ()

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

Returns
SyncService 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
if the connection with adb failed.

hasClients

public abstract boolean hasClients ()

Returns whether the IDevice has Clients.

Returns
boolean

installPackage

public abstract void installPackage (String packageFilePath, 
                boolean reinstall, 
                InstallReceiver receiver, 
                long maxTimeout, 
                long maxTimeToOutputResponse, 
                TimeUnit maxTimeUnits, 
                String... extraArgs)

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

Parameters
packageFilePath String: the absolute file system path to file on local host to install
reinstall boolean: set to true if re-install of app should be performed
receiver InstallReceiver: The InstallReceiver to be used to monitor the install and get final status.
maxTimeout long: the maximum timeout for the command to return. A value of 0 means no max timeout will be applied.
maxTimeToOutputResponse long: 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.
maxTimeUnits TimeUnit: Units for non-zero maxTimeout and maxTimeToOutputResponse values.
extraArgs String: optional extra arguments to pass. See 'adb shell pm install --help' for available options.
Throws
InstallException if the installation fails.

installPackage

public abstract void installPackage (String packageFilePath, 
                boolean reinstall, 
                InstallReceiver receiver, 
                String... extraArgs)

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

Parameters
packageFilePath String: the absolute file system path to file on local host to install
reinstall boolean: set to true if re-install of app should be performed
receiver InstallReceiver: The InstallReceiver to be used to monitor the install and get final status.
extraArgs String: optional extra arguments to pass. See 'adb shell pm install --help' for available options.
Throws
InstallException if the installation fails.

installPackage

public abstract void installPackage (String packageFilePath, 
                boolean reinstall, 
                String... extraArgs)

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

Parameters
packageFilePath String: the absolute file system path to file on local host to install
reinstall boolean: set to true if re-install of app should be performed
extraArgs String: optional extra arguments to pass. See 'adb shell pm install --help' for available options.
Throws
InstallException if the installation fails.

installPackages

public void installPackages ( apks, 
                boolean reinstall, 
                 installOptions)

Installs an Android application made of several APK files (one main and 0..n split packages) with default timeout

Parameters
apks : list of apks to install (1 main APK + 0..n split apks)
reinstall boolean: set to true if re-install of app should be performed
installOptions : optional extra arguments to pass. See 'adb shell pm install --help' for available options.
Throws
InstallException if the installation fails.

installPackages

public abstract void installPackages ( apks, 
                boolean reinstall, 
                 installOptions, 
                long timeout, 
                TimeUnit timeoutUnit)

Installs an Android application made of several APK files (one main and 0..n split packages)

Parameters
apks : list of apks to install (1 main APK + 0..n split apks)
reinstall boolean: set to true if re-install of app should be performed
installOptions : optional extra arguments to pass. See 'adb shell pm install --help' for available options.
timeout long: installation timeout
timeoutUnit TimeUnit: ERROR(/TimeUnit) corresponding to the timeout parameter
Throws
InstallException if the installation fails.

installRemotePackage

public abstract void installRemotePackage (String remoteFilePath, 
                boolean reinstall, 
                InstallReceiver receiver, 
                String... extraArgs)

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

Parameters
remoteFilePath String: absolute file path to package file on device
reinstall boolean: set to true if re-install of app should be performed
receiver InstallReceiver: The InstallReceiver to be used to monitor the install and get final status.
extraArgs String: optional extra arguments to pass. See 'adb shell pm install --help' for available options.
Throws
InstallException if the installation fails.

installRemotePackage

public abstract void installRemotePackage (String remoteFilePath, 
                boolean reinstall, 
                String... extraArgs)

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

Parameters
remoteFilePath String: absolute file path to package file on device
reinstall boolean: set to true if re-install of app should be performed
extraArgs String: optional extra arguments to pass. See 'adb shell pm install --help' for available options.
Throws
InstallException if the installation fails.

installRemotePackage

public abstract void installRemotePackage (String remoteFilePath, 
                boolean reinstall, 
                InstallReceiver receiver, 
                long maxTimeout, 
                long maxTimeToOutputResponse, 
                TimeUnit maxTimeUnits, 
                String... extraArgs)

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

Parameters
remoteFilePath String: absolute file path to package file on device
reinstall boolean: set to true if re-install of app should be performed
receiver InstallReceiver: The InstallReceiver to be used to monitor the install and get final status.
maxTimeout long: the maximum timeout for the command to return. A value of 0 means no max timeout will be applied.
maxTimeToOutputResponse long: 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.
maxTimeUnits TimeUnit: Units for non-zero maxTimeout and maxTimeToOutputResponse values.
extraArgs String: optional extra arguments to pass. See 'adb shell pm install --help' for available options.
Throws
InstallException if the installation fails.

installRemotePackages

public void installRemotePackages ( remoteApks, 
                boolean reinstall, 
                 installOptions)

Installs an Android application made of several APK files sitting locally on the device with default timeout

Parameters
remoteApks : list of apk file paths on the device to install
reinstall boolean: set to true if re-install of app should be performed
installOptions : optional extra arguments to pass. See 'adb shell pm install --help' for available options.
Throws
InstallException if the installation fails.

installRemotePackages

public void installRemotePackages ( remoteApks, 
                boolean reinstall, 
                 installOptions, 
                long timeout, 
                TimeUnit timeoutUnit)

Installs an Android application made of several APK files sitting locally on the device

Parameters
remoteApks : list of apk file paths sitting on the device to install
reinstall boolean: set to true if re-install of app should be performed
installOptions : optional extra arguments to pass. See 'adb shell pm install --help' for available options.
timeout long: installation timeout
timeoutUnit TimeUnit: ERROR(/TimeUnit) corresponding to the timeout parameter
Throws
InstallException if the installation fails.

isBootLoader

public abstract boolean isBootLoader ()

Returns if the device is in bootloader mode.

Returns
boolean true if getState() returns DeviceState.BOOTLOADER.

isEmulator

public abstract boolean isEmulator ()

Returns true if the device is an emulator.

Returns
boolean

isOffline

public abstract boolean isOffline ()

Returns if the device is offline.

Returns
boolean true if getState() returns DeviceState.OFFLINE.

isOnline

public abstract boolean isOnline ()

Returns if the device is ready.

Returns
boolean true if getState() returns DeviceState.ONLINE.

isRoot

public abstract boolean isRoot ()

Queries the current root-status of the device. See "adb root" for more information.

Returns
boolean true if the adb daemon is running as root, otherwise false.
Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command.
ShellCommandUnresponsiveException

kill

public void kill (String applicationName)

Kills an application by its application name. This only destroy the activities, leaving its state in the Android system alone.

Parameters
applicationName String: the name of the application

pullFile

public abstract void pullFile (String remote, 
                String local)

Pulls a single file.

Parameters
remote String: the full path to the remote file
local String: The local destination.
Throws
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.

push

public void push (String[] local, 
                String remote)

Pushes several files or directories.

Parameters
local String: the local files to push
remote String: the remote path representing a directory
Throws
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 some files could not be pushed

pushFile

public abstract void pushFile (String local, 
                String remote)

Pushes a single file.

Parameters
local String: the local filepath.
remote String: the remote filepath
Throws
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 the file could not be pushed

rawBinder

public SocketChannel rawBinder (String service, 
                String[] parameters)

Invoke the Android Binder Bridge service on a remote device. Return a socket channel that is connected to the device binder command.

Ownership of the SocketChannel is relinquished to the caller, it must be explicitly closed after usage.

Parameters
service String: the name of the Android service to connect to
parameters String: the parameters of the binder command
Returns
SocketChannel A SocketChannel connected to the executing process on the device. after use.
Throws
AdbCommandRejectedException
TimeoutException

rawExec

public SocketChannel rawExec (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.

Ownership of the SocketChannel is relinquished to the caller, it must be explicitly closed after usage.

Parameters
executable String

parameters String

Returns
SocketChannel A SocketChannel connected to the executing process on the device. after use.
Throws
AdbCommandRejectedException
TimeoutException

reboot

public abstract void reboot (String into)

Reboot the device.

Parameters
into String: 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

removeForward

public void removeForward (int localPort)

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

Parameters
localPort int: the local port to forward
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 void removeForward (int localPort, 
                int remotePort)

This method is deprecated.
Use removeForward(int)

Parameters
localPort int

remotePort int

Throws
AdbCommandRejectedException
TimeoutException

removeForward

public void removeForward (int localPort, 
                String remoteSocketName, 
                IDevice.DeviceUnixSocketNamespace namespace)

This method is deprecated.
Use removeForward(int)

Parameters
localPort int

remoteSocketName String

namespace IDevice.DeviceUnixSocketNamespace

Throws
AdbCommandRejectedException
TimeoutException

removeRemotePackage

public abstract void removeRemotePackage (String remoteFilePath)

Removes a file from device.

Parameters
remoteFilePath String: path on device of file to remove
Throws
InstallException if the installation fails.

removeReverse

public void removeReverse (int remotePort)

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

Parameters
remotePort int: the remote port.
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 abstract boolean root ()

Ask the adb daemon to become root on the device. This may silently fail, and can only succeed on developer builds. See "adb root" for more information.

Returns
boolean true if the adb daemon is running as root, otherwise false.
Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command.
ShellCommandUnresponsiveException if the root status cannot be queried.
IOException

startScreenRecorder

public abstract void startScreenRecorder (String remoteFilePath, 
                ScreenRecorderOptions options, 
                IShellOutputReceiver receiver)

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

Parameters
remoteFilePath String

options ScreenRecorderOptions

receiver IShellOutputReceiver

Throws
AdbCommandRejectedException
ShellCommandUnresponsiveException
TimeoutException

supportsFeature

public abstract boolean supportsFeature (IDevice.HardwareFeature feature)

Returns whether this device supports the given hardware feature.

Parameters
feature IDevice.HardwareFeature

Returns
boolean

supportsFeature

public abstract boolean supportsFeature (IDevice.Feature feature)

Returns whether this device supports the given software feature.

Parameters
feature IDevice.Feature

Returns
boolean

syncPackageToDevice

public abstract String syncPackageToDevice (String localFilePath)

Pushes a file to device

Parameters
localFilePath String: the absolute path to file on local host
Returns
String String destination path on device for file
Throws
TimeoutException in case of timeout on the connection.
AdbCommandRejectedException if adb rejects the command
in case of I/O error on the connection.
SyncException if an error happens during the push of the package on the device.

uninstallApp

public abstract String uninstallApp (String applicationID, 
                String... extraArgs)

Uninstalls an app from the device.

Parameters
applicationID String: the Android application ID to uninstall
extraArgs String: optional extra arguments to pass. See 'adb shell pm install --help' for available options.
Returns
String a String with an error code, or null if success.
Throws
InstallException if the uninstallation fails.

uninstallPackage

public abstract String uninstallPackage (String packageName)

Uninstalls a package from the device.

Parameters
packageName String: the Android application ID to uninstall
Returns
String a String with an error code, or null if success.
Throws
InstallException if the uninstallation fails.