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      * Rudely allocate a device, even if its not currently available.
72      * <p/>
73      * Will have no effect if device is already allocated.
74      *
75      * @param serial the device serial to allocate
76      * @return the {@link ITestDevice}, or <code>null</code> if it could not be allocated
77      */
forceAllocateDevice(String serial)78     public ITestDevice forceAllocateDevice(String serial);
79 
80     /**
81      * Return a device to the pool
82      * <p/>
83      * Attempts to return a device that hasn't been previously allocated will be ignored.
84      *
85      * @param device the {@link ITestDevice} to free
86      * @param state the {@link com.android.tradefed.device.FreeDeviceState}. Used to control if
87      *        device is returned to available device pool.
88      */
freeDevice(ITestDevice device, FreeDeviceState state)89     public void freeDevice(ITestDevice device, FreeDeviceState state);
90 
91     /**
92      * Helper method to launch emulator.
93      * <p/>
94      * Will launch the emulator as specified by the caller
95      *
96      * @param device the placeholder {@link ITestDevice} representing allocated emulator device
97      * @param bootTimeout the time in ms to wait for the emulator to boot
98      * @param runUtil
99      * @param emulatorArgs command line arguments to launch the emulator
100      * @throws DeviceNotAvailableException if emulator fails to boot or come online
101      */
launchEmulator(ITestDevice device, long bootTimeout, IRunUtil runUtil, List<String> emulatorArgs)102     void launchEmulator(ITestDevice device, long bootTimeout, IRunUtil runUtil,
103             List<String> emulatorArgs) throws DeviceNotAvailableException;
104 
105     /**
106      * Shut down the given emulator.
107      * <p/>
108      * Blocks until emulator disappears from adb. Will have no effect if emulator is already not
109      * available.
110      *
111      * @param device the {@link ITestDevice} representing emulator to shut down
112      * @throws DeviceNotAvailableException if emulator fails to shut down
113      */
killEmulator(ITestDevice device)114     public void killEmulator(ITestDevice device) throws DeviceNotAvailableException;
115 
116     /**
117      * Connect to a device with adb-over-tcp
118      * <p/>
119      * This method allocates a new device, which should eventually be freed via
120      * {@link #disconnectFromTcpDevice(ITestDevice)}
121      * <p/>
122      * The returned {@link ITestDevice} will be online, but may not be responsive.
123      * <p/>
124      * Note that performing action such as a reboot on a tcp connected device, will sever the
125      * tcp connection to the device, and result in a {@link DeviceNotAvailableException}
126      *
127      * @param ipAndPort the original ip address and port of the device to connect to
128      * @return the {@link ITestDevice} or <code>null</code> if a tcp connection could not be formed
129      */
connectToTcpDevice(String ipAndPort)130     public ITestDevice connectToTcpDevice(String ipAndPort);
131 
132     /**
133      * Disconnect from an adb-over-tcp connected device.
134      * <p/>
135      * Switches the device back to usb mode, and frees it.
136      *
137      * @param tcpDevice the device currently in tcp mode, previously allocated via
138      *            {@link #connectToTcpDevice(String)}
139      * @return <code>true</code> if switch to usb mode was successful
140      */
disconnectFromTcpDevice(ITestDevice tcpDevice)141     public boolean disconnectFromTcpDevice(ITestDevice tcpDevice);
142 
143     /**
144      * A helper method that switches the given usb device to adb-over-tcp mode, and then connects to
145      * it via {@link #connectToTcpDevice(String)}.
146      *
147      * @param usbDevice the device currently in usb mode
148      * @return the newly allocated {@link ITestDevice} in tcp mode or <code>null</code> if a tcp
149      *         connection could not be formed
150      * @throws DeviceNotAvailableException if the connection with <var>usbDevice</var> was lost and
151      *         could not be recovered
152      */
reconnectDeviceToTcp(ITestDevice usbDevice)153     public ITestDevice reconnectDeviceToTcp(ITestDevice usbDevice)
154             throws DeviceNotAvailableException;
155 
156     /**
157      * Stops device monitoring services, and terminates the ddm library.
158      * <p/>
159      * This must be called upon application termination.
160      *
161      * @see AndroidDebugBridge#terminate()
162      */
terminate()163     public void terminate();
164 
165     /** Stops the device recovery thread. */
terminateDeviceRecovery()166     public void terminateDeviceRecovery();
167 
168     /** Stop the Device Monitors. */
terminateDeviceMonitor()169     public void terminateDeviceMonitor();
170 
171     /** Like {@link #terminate()}, but attempts to forcefully shut down adb as well. */
terminateHard()172     public void terminateHard();
173 
174     /** Stop adb bridge and services depend on adb connections. */
stopAdbBridge()175     public void stopAdbBridge();
176 
177     /**
178      * Restart (if {@link #stopAdbBridge()} was called) adb bridge and services depend on adb
179      * connections.
180      */
restartAdbBridge()181     public void restartAdbBridge();
182 
183     /**
184      * Returns a map of all known devices and their state
185      *
186      * @return a list of device serials and their {@link
187      *     com.android.tradefed.device.DeviceAllocationState}
188      */
listAllDevices()189     public List<DeviceDescriptor> listAllDevices();
190 
191     /**
192      * Output a user-friendly description containing list of known devices, their state, and
193      * values for commonly used {@link IDeviceSelection} options.
194      *
195      * @param printWriter the {@link PrintWriter} to output the description to
196      */
displayDevicesInfo(PrintWriter printWriter)197     public void displayDevicesInfo(PrintWriter printWriter);
198 
199     /**
200      * Informs the manager that a listener is interested in fastboot state changes.
201      * <p/>
202      * Currently a {@link IDeviceManager} will only monitor devices in fastboot if there are one or
203      * more active listeners.
204      * <p/>
205      * TODO: this is a bit of a hack - find a better solution
206      *
207      * @param listener
208      */
addFastbootListener(IFastbootListener listener)209     public void addFastbootListener(IFastbootListener listener);
210 
211     /**
212      * Informs the manager that a listener is no longer interested in fastboot state changes.
213      * @param listener
214      */
removeFastbootListener(IFastbootListener listener)215     public void removeFastbootListener(IFastbootListener listener);
216 
217     /**
218      * Determine if given serial represents a null device
219      */
isNullDevice(String serial)220     public boolean isNullDevice(String serial);
221 
222     /**
223      * Determine if given serial represents a emulator
224      */
isEmulator(String serial)225     public boolean isEmulator(String serial);
226 
227     /**
228      * Adds a {@link IDeviceMonitor}
229      */
addDeviceMonitor(IDeviceMonitor mon)230     public void addDeviceMonitor(IDeviceMonitor mon);
231 
232     /**
233      * Removes a previously added {@link IDeviceMonitor}. Has no effect if mon has not been added.
234      */
removeDeviceMonitor(IDeviceMonitor mon)235     public void removeDeviceMonitor(IDeviceMonitor mon);
236 
237     /**
238      * Returns the path to the fastboot binary path to use.
239      */
getFastbootPath()240     public String getFastbootPath();
241 
242     /**
243      * Wait until a first physical device is connected. If a device was connected before, it
244      * returns directly True. If no device was added, it returns false after timeout.
245      *
246      * @param timeout time to wait in millisecond before returning false.
247      */
waitForFirstDeviceAdded(long timeout)248     public boolean waitForFirstDeviceAdded(long timeout);
249 
250     /**
251      * Get the number of available flashing permits
252      *
253      * @return Number of available flashing permits or Integer.MAX_VALUE if not available.
254      */
getAvailableFlashingPermits()255     public int getAvailableFlashingPermits();
256 
257     /**
258      * Request permission to flash.  If the number of concurrent flashers is limited, this will
259      * wait in line in order to remain under the flash limit count.
260      */
takeFlashingPermit()261     public void takeFlashingPermit();
262 
263     /**
264      * Restore a flashing permit that we acquired previously
265      */
returnFlashingPermit()266     public void returnFlashingPermit();
267 
268     /** Get the adb version currently in use by the device manager. */
getAdbVersion()269     public String getAdbVersion();
270 }
271