IDeviceManager

public interface IDeviceManager

com.android.tradefed.device.IDeviceManager

Interface for managing the set of available devices for testing.

Summary

Nested classes

interface IDeviceManager.IFastbootListener

A listener for fastboot state changes. 

Public methods

abstract void addDeviceMonitor(IDeviceMonitor mon)

Adds a IDeviceMonitor

abstract void addFastbootListener(IDeviceManager.IFastbootListener listener)

Informs the manager that a listener is interested in fastboot state changes.

abstract ITestDevice allocateDevice(IDeviceSelection options, boolean isTemporary)

Request a device for testing that meets certain criteria.

abstract ITestDevice allocateDevice(IDeviceSelection options)

Request a device for testing that meets certain criteria.

abstract ITestDevice allocateDevice()

Request a physical device for testing

abstract ITestDevice connectToTcpDevice(String ipAndPort)

Connect to a device with adb-over-tcp

This method allocates a new device, which should eventually be freed via disconnectFromTcpDevice(com.android.tradefed.device.ITestDevice)

The returned ITestDevice will be online, but may not be responsive.

abstract boolean disconnectFromTcpDevice(ITestDevice tcpDevice)

Disconnect from an adb-over-tcp connected device.

abstract void displayDevicesInfo(PrintWriter printWriter, boolean includeStub)

Output a user-friendly description containing list of known devices, their state, and values for commonly used IDeviceSelection options.

abstract ITestDevice forceAllocateDevice(String serial)

Rudely allocate a device, even if its not currently available.

abstract void freeDevice(ITestDevice device, FreeDeviceState state)

Return a device to the pool

Attempts to return a device that hasn't been previously allocated will be ignored.

abstract String getAdbPath()

Returns the path to the adb binary to use.

abstract String getAdbVersion()

Get the adb version currently in use by the device manager.

abstract int getAvailableFlashingPermits()

Get the number of available flashing permits

abstract DeviceDescriptor getDeviceDescriptor(String serial)

Returns the DeviceDescriptor with the given serial.

abstract String getFastbootPath()

Returns the path to the fastboot binary to use.

abstract void init(IDeviceSelection globalDeviceFilter, deviceMonitors)

Initialize the device manager with a device filter.

abstract void init()

Initialize the device manager.

abstract boolean isEmulator(String serial)

Determine if given serial represents a emulator

abstract boolean isNullDevice(String serial)

Determine if given serial represents a null device

abstract void killEmulator(ITestDevice device)

Shut down the given emulator.

abstract void launchEmulator(ITestDevice device, long bootTimeout, IRunUtil runUtil, emulatorArgs)

Helper method to launch emulator.

abstract listAllDevices()

Returns a list of DeviceDescriptors for all known devices

abstract ITestDevice reconnectDeviceToTcp(ITestDevice usbDevice)

A helper method that switches the given usb device to adb-over-tcp mode, and then connects to it via connectToTcpDevice(String).

abstract void removeDeviceMonitor(IDeviceMonitor mon)

Removes a previously added IDeviceMonitor.

abstract void removeFastbootListener(IDeviceManager.IFastbootListener listener)

Informs the manager that a listener is no longer interested in fastboot state changes.

abstract void restartAdbBridge()

Restart (if stopAdbBridge() was called) adb bridge and services depend on adb connections.

abstract void returnFlashingPermit()

Restore a flashing permit that we acquired previously

abstract void stopAdbBridge()

Stop adb bridge and services depend on adb connections.

abstract void takeFlashingPermit()

Request permission to flash.

abstract void terminate()

Stops device monitoring services, and terminates the ddm library.

abstract void terminateDeviceMonitor()

Stop the Device Monitors.

abstract void terminateDeviceRecovery()

Stops the device recovery thread.

abstract void terminateHard()

Like terminate(), but attempts to forcefully shut down adb as well.

abstract boolean waitForFirstDeviceAdded(long timeout)

Wait until a first physical device is connected.

Public methods

addDeviceMonitor

public abstract void addDeviceMonitor (IDeviceMonitor mon)

Adds a IDeviceMonitor

Parameters
mon IDeviceMonitor

addFastbootListener

public abstract void addFastbootListener (IDeviceManager.IFastbootListener listener)

Informs the manager that a listener is interested in fastboot state changes.

Currently a IDeviceManager will only monitor devices in fastboot if there are one or more active listeners.

TODO: this is a bit of a hack - find a better solution

allocateDevice

public abstract ITestDevice allocateDevice (IDeviceSelection options, 
                boolean isTemporary)

Request a device for testing that meets certain criteria.

Parameters
options IDeviceSelection: the IDeviceSelection the device should meet.
isTemporary boolean: whether or not a temporary NullDevice should be created.
Returns
ITestDevice a ITestDevice for testing, or null if one is not available

allocateDevice

public abstract ITestDevice allocateDevice (IDeviceSelection options)

Request a device for testing that meets certain criteria.

Parameters
options IDeviceSelection: the IDeviceSelection the device should meet.
Returns
ITestDevice a ITestDevice for testing, or null if one is not available

allocateDevice

public abstract ITestDevice allocateDevice ()

Request a physical device for testing

Returns
ITestDevice a ITestDevice for testing, or null if one is not available

connectToTcpDevice

public abstract ITestDevice connectToTcpDevice (String ipAndPort)

Connect to a device with adb-over-tcp

This method allocates a new device, which should eventually be freed via disconnectFromTcpDevice(com.android.tradefed.device.ITestDevice)

The returned ITestDevice will be online, but may not be responsive.

Note that performing action such as a reboot on a tcp connected device, will sever the tcp connection to the device, and result in a DeviceNotAvailableException

Parameters
ipAndPort String: the original ip address and port of the device to connect to
Returns
ITestDevice the ITestDevice or null if a tcp connection could not be formed

disconnectFromTcpDevice

public abstract boolean disconnectFromTcpDevice (ITestDevice tcpDevice)

Disconnect from an adb-over-tcp connected device.

Switches the device back to usb mode, and frees it.

Parameters
tcpDevice ITestDevice: the device currently in tcp mode, previously allocated via connectToTcpDevice(String)
Returns
boolean true if switch to usb mode was successful

displayDevicesInfo

public abstract void displayDevicesInfo (PrintWriter printWriter, 
                boolean includeStub)

Output a user-friendly description containing list of known devices, their state, and values for commonly used IDeviceSelection options.

Parameters
printWriter PrintWriter: the ERROR(/PrintWriter) to output the description to
includeStub boolean: Whether or not to display stub devices too.

forceAllocateDevice

public abstract ITestDevice forceAllocateDevice (String serial)

Rudely allocate a device, even if its not currently available.

Will have no effect if device is already allocated.

Parameters
serial String: the device serial to allocate
Returns
ITestDevice the ITestDevice, or null if it could not be allocated

freeDevice

public abstract void freeDevice (ITestDevice device, 
                FreeDeviceState state)

Return a device to the pool

Attempts to return a device that hasn't been previously allocated will be ignored.

Parameters
device ITestDevice: the ITestDevice to free
state FreeDeviceState: the FreeDeviceState. Used to control if device is returned to available device pool.

getAdbPath

public abstract String getAdbPath ()

Returns the path to the adb binary to use.

Returns
String

getAdbVersion

public abstract String getAdbVersion ()

Get the adb version currently in use by the device manager.

Returns
String

getAvailableFlashingPermits

public abstract int getAvailableFlashingPermits ()

Get the number of available flashing permits

Returns
int Number of available flashing permits or Integer.MAX_VALUE if not available.

getDeviceDescriptor

public abstract DeviceDescriptor getDeviceDescriptor (String serial)

Returns the DeviceDescriptor with the given serial.

Parameters
serial String: serial number for the device to get
Returns
DeviceDescriptor the DeviceDescriptor for the selected device, or null if the serial does not match a known device.

getFastbootPath

public abstract String getFastbootPath ()

Returns the path to the fastboot binary to use.

Returns
String

init

public abstract void init (IDeviceSelection globalDeviceFilter, 
                 deviceMonitors)

Initialize the device manager with a device filter. This filter can be used to instruct the DeviceManager to ignore certain connected devices.

Parameters
globalDeviceFilter IDeviceSelection: the device filter

deviceMonitors

init

public abstract void init ()

Initialize the device manager. This must be called once and only once before any other methods are called.

isEmulator

public abstract boolean isEmulator (String serial)

Determine if given serial represents a emulator

Parameters
serial String

Returns
boolean

isNullDevice

public abstract boolean isNullDevice (String serial)

Determine if given serial represents a null device

Parameters
serial String

Returns
boolean

killEmulator

public abstract void killEmulator (ITestDevice device)

Shut down the given emulator.

Blocks until emulator disappears from adb. Will have no effect if emulator is already not available.

Parameters
device ITestDevice: the ITestDevice representing emulator to shut down
Throws
DeviceNotAvailableException if emulator fails to shut down

launchEmulator

public abstract void launchEmulator (ITestDevice device, 
                long bootTimeout, 
                IRunUtil runUtil, 
                 emulatorArgs)

Helper method to launch emulator.

Will launch the emulator as specified by the caller

Parameters
device ITestDevice: the placeholder ITestDevice representing allocated emulator device
bootTimeout long: the time in ms to wait for the emulator to boot
emulatorArgs : command line arguments to launch the emulator
Throws
DeviceNotAvailableException if emulator fails to boot or come online

listAllDevices

public abstract  listAllDevices ()

Returns a list of DeviceDescriptors for all known devices

Returns
a list of DeviceDescriptor for all known devices

reconnectDeviceToTcp

public abstract ITestDevice reconnectDeviceToTcp (ITestDevice usbDevice)

A helper method that switches the given usb device to adb-over-tcp mode, and then connects to it via connectToTcpDevice(String).

Parameters
usbDevice ITestDevice: the device currently in usb mode
Returns
ITestDevice the newly allocated ITestDevice in tcp mode or null if a tcp connection could not be formed
Throws
DeviceNotAvailableException if the connection with usbDevice was lost and could not be recovered

removeDeviceMonitor

public abstract void removeDeviceMonitor (IDeviceMonitor mon)

Removes a previously added IDeviceMonitor. Has no effect if mon has not been added.

Parameters
mon IDeviceMonitor

removeFastbootListener

public abstract void removeFastbootListener (IDeviceManager.IFastbootListener listener)

Informs the manager that a listener is no longer interested in fastboot state changes.

restartAdbBridge

public abstract void restartAdbBridge ()

Restart (if stopAdbBridge() was called) adb bridge and services depend on adb connections.

returnFlashingPermit

public abstract void returnFlashingPermit ()

Restore a flashing permit that we acquired previously

stopAdbBridge

public abstract void stopAdbBridge ()

Stop adb bridge and services depend on adb connections.

takeFlashingPermit

public abstract void takeFlashingPermit ()

Request permission to flash. If the number of concurrent flashers is limited, this will wait in line in order to remain under the flash limit count.

terminate

public abstract void terminate ()

Stops device monitoring services, and terminates the ddm library.

This must be called upon application termination.

terminateDeviceMonitor

public abstract void terminateDeviceMonitor ()

Stop the Device Monitors.

terminateDeviceRecovery

public abstract void terminateDeviceRecovery ()

Stops the device recovery thread.

terminateHard

public abstract void terminateHard ()

Like terminate(), but attempts to forcefully shut down adb as well.

waitForFirstDeviceAdded

public abstract boolean waitForFirstDeviceAdded (long timeout)

Wait until a first physical device is connected. If a device was connected before, it returns directly True. If no device was added, it returns false after timeout.

Parameters
timeout long: time to wait in millisecond before returning false.

Returns
boolean