1 /* 2 * Copyright (C) 2010 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.tradefed.device; 18 19 import com.android.ddmlib.AndroidDebugBridge; 20 import com.android.tradefed.command.remote.DeviceDescriptor; 21 import com.android.tradefed.util.IRunUtil; 22 23 import java.io.PrintWriter; 24 import java.util.List; 25 26 /** 27 * Interface for managing the set of available devices for testing. 28 */ 29 public interface IDeviceManager { 30 /** 31 * A listener for fastboot state changes. 32 */ 33 public static interface IFastbootListener { 34 /** 35 * Callback when fastboot state has been updated for all devices. 36 */ stateUpdated()37 public void stateUpdated(); 38 } 39 40 /** 41 * Initialize the device manager. This must be called once and only once before any other 42 * methods are called. 43 */ init()44 public void init(); 45 46 /** 47 * Initialize the device manager with a device filter. This filter can be used to instruct 48 * the DeviceManager to ignore certain connected devices. 49 * 50 * @param globalDeviceFilter the device filter 51 */ init(IDeviceSelection globalDeviceFilter, List<IDeviceMonitor> deviceMonitors)52 public void init(IDeviceSelection globalDeviceFilter, List<IDeviceMonitor> deviceMonitors); 53 54 /** 55 * Request a physical device for testing 56 * 57 * @return a {@link ITestDevice} for testing, or <code>null</code> if one is not available 58 */ allocateDevice()59 public ITestDevice allocateDevice(); 60 61 /** 62 * Request a device for testing that meets certain criteria. 63 * 64 * @param options the {@link IDeviceSelection} the device should meet. 65 * @return a {@link ITestDevice} for testing, or <code>null</code> if one 66 * is not available 67 */ allocateDevice(IDeviceSelection options)68 public ITestDevice allocateDevice(IDeviceSelection options); 69 70 /** 71 * Request a device for testing that meets certain criteria. 72 * 73 * @param options the {@link IDeviceSelection} the device should meet. 74 * @param isTemporary whether or not a temporary NullDevice should be created. 75 * @return a {@link ITestDevice} for testing, or <code>null</code> if one is not available 76 */ allocateDevice(IDeviceSelection options, boolean isTemporary)77 public ITestDevice allocateDevice(IDeviceSelection options, boolean isTemporary); 78 79 /** 80 * Rudely allocate a device, even if its not currently available. 81 * <p/> 82 * Will have no effect if device is already allocated. 83 * 84 * @param serial the device serial to allocate 85 * @return the {@link ITestDevice}, or <code>null</code> if it could not be allocated 86 */ forceAllocateDevice(String serial)87 public ITestDevice forceAllocateDevice(String serial); 88 89 /** 90 * Return a device to the pool 91 * <p/> 92 * Attempts to return a device that hasn't been previously allocated will be ignored. 93 * 94 * @param device the {@link ITestDevice} to free 95 * @param state the {@link com.android.tradefed.device.FreeDeviceState}. Used to control if 96 * device is returned to available device pool. 97 */ freeDevice(ITestDevice device, FreeDeviceState state)98 public void freeDevice(ITestDevice device, FreeDeviceState state); 99 100 /** 101 * Helper method to launch emulator. 102 * <p/> 103 * Will launch the emulator as specified by the caller 104 * 105 * @param device the placeholder {@link ITestDevice} representing allocated emulator device 106 * @param bootTimeout the time in ms to wait for the emulator to boot 107 * @param runUtil 108 * @param emulatorArgs command line arguments to launch the emulator 109 * @throws DeviceNotAvailableException if emulator fails to boot or come online 110 */ launchEmulator(ITestDevice device, long bootTimeout, IRunUtil runUtil, List<String> emulatorArgs)111 void launchEmulator(ITestDevice device, long bootTimeout, IRunUtil runUtil, 112 List<String> emulatorArgs) throws DeviceNotAvailableException; 113 114 /** 115 * Shut down the given emulator. 116 * <p/> 117 * Blocks until emulator disappears from adb. Will have no effect if emulator is already not 118 * available. 119 * 120 * @param device the {@link ITestDevice} representing emulator to shut down 121 * @throws DeviceNotAvailableException if emulator fails to shut down 122 */ killEmulator(ITestDevice device)123 public void killEmulator(ITestDevice device) throws DeviceNotAvailableException; 124 125 /** 126 * Connect to a device with adb-over-tcp 127 * <p/> 128 * This method allocates a new device, which should eventually be freed via 129 * {@link #disconnectFromTcpDevice(ITestDevice)} 130 * <p/> 131 * The returned {@link ITestDevice} will be online, but may not be responsive. 132 * <p/> 133 * Note that performing action such as a reboot on a tcp connected device, will sever the 134 * tcp connection to the device, and result in a {@link DeviceNotAvailableException} 135 * 136 * @param ipAndPort the original ip address and port of the device to connect to 137 * @return the {@link ITestDevice} or <code>null</code> if a tcp connection could not be formed 138 */ connectToTcpDevice(String ipAndPort)139 public ITestDevice connectToTcpDevice(String ipAndPort); 140 141 /** 142 * Disconnect from an adb-over-tcp connected device. 143 * <p/> 144 * Switches the device back to usb mode, and frees it. 145 * 146 * @param tcpDevice the device currently in tcp mode, previously allocated via 147 * {@link #connectToTcpDevice(String)} 148 * @return <code>true</code> if switch to usb mode was successful 149 */ disconnectFromTcpDevice(ITestDevice tcpDevice)150 public boolean disconnectFromTcpDevice(ITestDevice tcpDevice); 151 152 /** 153 * A helper method that switches the given usb device to adb-over-tcp mode, and then connects to 154 * it via {@link #connectToTcpDevice(String)}. 155 * 156 * @param usbDevice the device currently in usb mode 157 * @return the newly allocated {@link ITestDevice} in tcp mode or <code>null</code> if a tcp 158 * connection could not be formed 159 * @throws DeviceNotAvailableException if the connection with <var>usbDevice</var> was lost and 160 * could not be recovered 161 */ reconnectDeviceToTcp(ITestDevice usbDevice)162 public ITestDevice reconnectDeviceToTcp(ITestDevice usbDevice) 163 throws DeviceNotAvailableException; 164 165 /** 166 * Stops device monitoring services, and terminates the ddm library. 167 * <p/> 168 * This must be called upon application termination. 169 * 170 * @see AndroidDebugBridge#terminate() 171 */ terminate()172 public void terminate(); 173 174 /** Stops the device recovery thread. */ terminateDeviceRecovery()175 public void terminateDeviceRecovery(); 176 177 /** Stop the Device Monitors. */ terminateDeviceMonitor()178 public void terminateDeviceMonitor(); 179 180 /** Like {@link #terminate()}, but attempts to forcefully shut down adb as well. */ terminateHard()181 public void terminateHard(); 182 183 /** Stop adb bridge and services depend on adb connections. */ stopAdbBridge()184 public void stopAdbBridge(); 185 186 /** 187 * Restart (if {@link #stopAdbBridge()} was called) adb bridge and services depend on adb 188 * connections. 189 */ restartAdbBridge()190 public void restartAdbBridge(); 191 192 /** 193 * Returns a list of DeviceDescriptors for all known devices 194 * 195 * @return a list of {@link DeviceDescriptor} for all known devices 196 */ listAllDevices()197 public List<DeviceDescriptor> listAllDevices(); 198 199 /** 200 * Returns the DeviceDescriptor with the given serial. 201 * 202 * @param serial serial number for the device to get 203 * @return the {@link DeviceDescriptor} for the selected device, or null if the serial does not 204 * match a known device. 205 */ getDeviceDescriptor(String serial)206 public DeviceDescriptor getDeviceDescriptor(String serial); 207 208 /** 209 * Output a user-friendly description containing list of known devices, their state, and values 210 * for commonly used {@link IDeviceSelection} options. 211 * 212 * @param printWriter the {@link PrintWriter} to output the description to 213 * @param includeStub Whether or not to display stub devices too. 214 */ displayDevicesInfo(PrintWriter printWriter, boolean includeStub)215 public void displayDevicesInfo(PrintWriter printWriter, boolean includeStub); 216 217 /** 218 * Informs the manager that a listener is interested in fastboot state changes. 219 * <p/> 220 * Currently a {@link IDeviceManager} will only monitor devices in fastboot if there are one or 221 * more active listeners. 222 * <p/> 223 * TODO: this is a bit of a hack - find a better solution 224 * 225 * @param listener 226 */ addFastbootListener(IFastbootListener listener)227 public void addFastbootListener(IFastbootListener listener); 228 229 /** 230 * Informs the manager that a listener is no longer interested in fastboot state changes. 231 * @param listener 232 */ removeFastbootListener(IFastbootListener listener)233 public void removeFastbootListener(IFastbootListener listener); 234 235 /** 236 * Determine if given serial represents a null device 237 */ isNullDevice(String serial)238 public boolean isNullDevice(String serial); 239 240 /** 241 * Determine if given serial represents a emulator 242 */ isEmulator(String serial)243 public boolean isEmulator(String serial); 244 245 /** 246 * Adds a {@link IDeviceMonitor} 247 */ addDeviceMonitor(IDeviceMonitor mon)248 public void addDeviceMonitor(IDeviceMonitor mon); 249 250 /** 251 * Removes a previously added {@link IDeviceMonitor}. Has no effect if mon has not been added. 252 */ removeDeviceMonitor(IDeviceMonitor mon)253 public void removeDeviceMonitor(IDeviceMonitor mon); 254 255 /** Returns the path to the adb binary to use. */ getAdbPath()256 public String getAdbPath(); 257 258 /** Returns the path to the fastboot binary to use. */ getFastbootPath()259 public String getFastbootPath(); 260 261 /** 262 * Wait until a first physical device is connected. If a device was connected before, it 263 * returns directly True. If no device was added, it returns false after timeout. 264 * 265 * @param timeout time to wait in millisecond before returning false. 266 */ waitForFirstDeviceAdded(long timeout)267 public boolean waitForFirstDeviceAdded(long timeout); 268 269 /** 270 * Get the number of available flashing permits 271 * 272 * @return Number of available flashing permits or Integer.MAX_VALUE if not available. 273 */ getAvailableFlashingPermits()274 public int getAvailableFlashingPermits(); 275 276 /** 277 * Request permission to flash. If the number of concurrent flashers is limited, this will 278 * wait in line in order to remain under the flash limit count. 279 */ takeFlashingPermit()280 public void takeFlashingPermit(); 281 282 /** 283 * Restore a flashing permit that we acquired previously 284 */ returnFlashingPermit()285 public void returnFlashingPermit(); 286 287 /** Get the adb version currently in use by the device manager. */ getAdbVersion()288 public String getAdbVersion(); 289 } 290