• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2008 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.ddmlib;
18 
19 import com.android.ddmlib.log.LogReceiver;
20 
21 import java.io.IOException;
22 import java.util.Map;
23 
24 /**
25  *  A Device. It can be a physical device or an emulator.
26  */
27 public interface IDevice {
28 
29     public final static String PROP_BUILD_VERSION = "ro.build.version.release";
30     public final static String PROP_BUILD_API_LEVEL = "ro.build.version.sdk";
31     public final static String PROP_BUILD_CODENAME = "ro.build.version.codename";
32 
33     public final static String PROP_DEBUGGABLE = "ro.debuggable";
34 
35     /** Serial number of the first connected emulator. */
36     public final static String FIRST_EMULATOR_SN = "emulator-5554"; //$NON-NLS-1$
37     /** Device change bit mask: {@link DeviceState} change. */
38     public static final int CHANGE_STATE = 0x0001;
39     /** Device change bit mask: {@link Client} list change. */
40     public static final int CHANGE_CLIENT_LIST = 0x0002;
41     /** Device change bit mask: build info change. */
42     public static final int CHANGE_BUILD_INFO = 0x0004;
43 
44     /** @deprecated Use {@link #PROP_BUILD_API_LEVEL}. */
45     @Deprecated
46     public final static String PROP_BUILD_VERSION_NUMBER = PROP_BUILD_API_LEVEL;
47 
48     public final static String MNT_EXTERNAL_STORAGE = "EXTERNAL_STORAGE"; //$NON-NLS-1$
49     public final static String MNT_ROOT = "ANDROID_ROOT"; //$NON-NLS-1$
50     public final static String MNT_DATA = "ANDROID_DATA"; //$NON-NLS-1$
51 
52     /**
53      * The state of a device.
54      */
55     public static enum DeviceState {
56         BOOTLOADER("bootloader"), //$NON-NLS-1$
57         OFFLINE("offline"), //$NON-NLS-1$
58         ONLINE("device"), //$NON-NLS-1$
59         RECOVERY("recovery"); //$NON-NLS-1$
60 
61         private String mState;
62 
DeviceState(String state)63         DeviceState(String state) {
64             mState = state;
65         }
66 
67         /**
68          * Returns a {@link DeviceState} from the string returned by <code>adb devices</code>.
69          *
70          * @param state the device state.
71          * @return a {@link DeviceState} object or <code>null</code> if the state is unknown.
72          */
getState(String state)73         public static DeviceState getState(String state) {
74             for (DeviceState deviceState : values()) {
75                 if (deviceState.mState.equals(state)) {
76                     return deviceState;
77                 }
78             }
79             return null;
80         }
81     }
82 
83     /**
84      * Namespace of a Unix Domain Socket created on the device.
85      */
86     public static enum DeviceUnixSocketNamespace {
87         ABSTRACT("localabstract"),      //$NON-NLS-1$
88         FILESYSTEM("localfilesystem"),  //$NON-NLS-1$
89         RESERVED("localreserved");      //$NON-NLS-1$
90 
91         private String mType;
92 
DeviceUnixSocketNamespace(String type)93         private DeviceUnixSocketNamespace(String type) {
94             mType = type;
95         }
96 
getType()97         String getType() {
98             return mType;
99         }
100     };
101 
102     /**
103      * Returns the serial number of the device.
104      */
getSerialNumber()105     public String getSerialNumber();
106 
107     /**
108      * Returns the name of the AVD the emulator is running.
109      * <p/>This is only valid if {@link #isEmulator()} returns true.
110      * <p/>If the emulator is not running any AVD (for instance it's running from an Android source
111      * tree build), this method will return "<code>&lt;build&gt;</code>".
112      *
113      * @return the name of the AVD or <code>null</code> if there isn't any.
114      */
getAvdName()115     public String getAvdName();
116 
117     /**
118      * Returns a (humanized) name for this device. Typically this is the AVD name for AVD's, and
119      * a combination of the manufacturer name, model name & serial number for devices.
120      */
getName()121     public String getName();
122 
123     /**
124      * Returns the state of the device.
125      */
getState()126     public DeviceState getState();
127 
128     /**
129      * Returns the device properties. It contains the whole output of 'getprop'
130      */
getProperties()131     public Map<String, String> getProperties();
132 
133     /**
134      * Returns the number of property for this device.
135      */
getPropertyCount()136     public int getPropertyCount();
137 
138     /**
139      * Returns the cached property value.
140      *
141      * @param name the name of the value to return.
142      * @return the value or <code>null</code> if the property does not exist or has not yet been
143      * cached.
144      */
getProperty(String name)145     public String getProperty(String name);
146 
147     /**
148      * Returns <code>true></code> if properties have been cached
149      */
arePropertiesSet()150     public boolean arePropertiesSet();
151 
152     /**
153      * A variant of {@link #getProperty(String)} that will attempt to retrieve the given
154      * property from device directly, without using cache.
155      *
156      * @param name the name of the value to return.
157      * @return the value or <code>null</code> if the property does not exist
158      * @throws TimeoutException in case of timeout on the connection.
159      * @throws AdbCommandRejectedException if adb rejects the command
160      * @throws ShellCommandUnresponsiveException in case the shell command doesn't send output for a
161      *             given time.
162      * @throws IOException in case of I/O error on the connection.
163      */
getPropertySync(String name)164     public String getPropertySync(String name) throws TimeoutException,
165             AdbCommandRejectedException, ShellCommandUnresponsiveException, IOException;
166 
167     /**
168      * A combination of {@link #getProperty(String)} and {@link #getPropertySync(String)} that
169      * will attempt to retrieve the property from cache if available, and if not, will query the
170      * device directly.
171      *
172      * @param name the name of the value to return.
173      * @return the value or <code>null</code> if the property does not exist
174      * @throws TimeoutException in case of timeout on the connection.
175      * @throws AdbCommandRejectedException if adb rejects the command
176      * @throws ShellCommandUnresponsiveException in case the shell command doesn't send output for a
177      *             given time.
178      * @throws IOException in case of I/O error on the connection.
179      */
getPropertyCacheOrSync(String name)180     public String getPropertyCacheOrSync(String name) throws TimeoutException,
181             AdbCommandRejectedException, ShellCommandUnresponsiveException, IOException;
182 
183     /**
184      * Returns a mount point.
185      *
186      * @param name the name of the mount point to return
187      *
188      * @see #MNT_EXTERNAL_STORAGE
189      * @see #MNT_ROOT
190      * @see #MNT_DATA
191      */
getMountPoint(String name)192     public String getMountPoint(String name);
193 
194     /**
195      * Returns if the device is ready.
196      *
197      * @return <code>true</code> if {@link #getState()} returns {@link DeviceState#ONLINE}.
198      */
isOnline()199     public boolean isOnline();
200 
201     /**
202      * Returns <code>true</code> if the device is an emulator.
203      */
isEmulator()204     public boolean isEmulator();
205 
206     /**
207      * Returns if the device is offline.
208      *
209      * @return <code>true</code> if {@link #getState()} returns {@link DeviceState#OFFLINE}.
210      */
isOffline()211     public boolean isOffline();
212 
213     /**
214      * Returns if the device is in bootloader mode.
215      *
216      * @return <code>true</code> if {@link #getState()} returns {@link DeviceState#BOOTLOADER}.
217      */
isBootLoader()218     public boolean isBootLoader();
219 
220     /**
221      * Returns whether the {@link Device} has {@link Client}s.
222      */
hasClients()223     public boolean hasClients();
224 
225     /**
226      * Returns the array of clients.
227      */
getClients()228     public Client[] getClients();
229 
230     /**
231      * Returns a {@link Client} by its application name.
232      *
233      * @param applicationName the name of the application
234      * @return the <code>Client</code> object or <code>null</code> if no match was found.
235      */
getClient(String applicationName)236     public Client getClient(String applicationName);
237 
238     /**
239      * Returns a {@link SyncService} object to push / pull files to and from the device.
240      *
241      * @return <code>null</code> if the SyncService couldn't be created. This can happen if adb
242      *            refuse to open the connection because the {@link IDevice} is invalid
243      *            (or got disconnected).
244      * @throws TimeoutException in case of timeout on the connection.
245      * @throws AdbCommandRejectedException if adb rejects the command
246      * @throws IOException if the connection with adb failed.
247      */
getSyncService()248     public SyncService getSyncService()
249             throws TimeoutException, AdbCommandRejectedException, IOException;
250 
251     /**
252      * Returns a {@link FileListingService} for this device.
253      */
getFileListingService()254     public FileListingService getFileListingService();
255 
256     /**
257      * Takes a screen shot of the device and returns it as a {@link RawImage}.
258      *
259      * @return the screenshot as a <code>RawImage</code> or <code>null</code> if something
260      *            went wrong.
261      * @throws TimeoutException in case of timeout on the connection.
262      * @throws AdbCommandRejectedException if adb rejects the command
263      * @throws IOException in case of I/O error on the connection.
264      */
getScreenshot()265     public RawImage getScreenshot() throws TimeoutException, AdbCommandRejectedException,
266             IOException;
267 
268     /**
269      * Executes a shell command on the device, and sends the result to a <var>receiver</var>
270      * <p/>This is similar to calling
271      * <code>executeShellCommand(command, receiver, DdmPreferences.getTimeOut())</code>.
272      *
273      * @param command the shell command to execute
274      * @param receiver the {@link IShellOutputReceiver} that will receives the output of the shell
275      *            command
276      * @throws TimeoutException in case of timeout on the connection.
277      * @throws AdbCommandRejectedException if adb rejects the command
278      * @throws ShellCommandUnresponsiveException in case the shell command doesn't send output
279      *            for a given time.
280      * @throws IOException in case of I/O error on the connection.
281      *
282      * @see #executeShellCommand(String, IShellOutputReceiver, int)
283      * @see DdmPreferences#getTimeOut()
284      */
executeShellCommand(String command, IShellOutputReceiver receiver)285     public void executeShellCommand(String command, IShellOutputReceiver receiver)
286             throws TimeoutException, AdbCommandRejectedException, ShellCommandUnresponsiveException,
287             IOException;
288 
289     /**
290      * Executes a shell command on the device, and sends the result to a <var>receiver</var>.
291      * <p/><var>maxTimeToOutputResponse</var> is used as a maximum waiting time when expecting the
292      * command output from the device.<br>
293      * At any time, if the shell command does not output anything for a period longer than
294      * <var>maxTimeToOutputResponse</var>, then the method will throw
295      * {@link ShellCommandUnresponsiveException}.
296      * <p/>For commands like log output, a <var>maxTimeToOutputResponse</var> value of 0, meaning
297      * that the method will never throw and will block until the receiver's
298      * {@link IShellOutputReceiver#isCancelled()} returns <code>true</code>, should be
299      * used.
300      *
301      * @param command the shell command to execute
302      * @param receiver the {@link IShellOutputReceiver} that will receives the output of the shell
303      *            command
304      * @param maxTimeToOutputResponse the maximum amount of time during which the command is allowed
305      *            to not output any response. A value of 0 means the method will wait forever
306      *            (until the <var>receiver</var> cancels the execution) for command output and
307      *            never throw.
308      * @throws TimeoutException in case of timeout on the connection when sending the command.
309      * @throws AdbCommandRejectedException if adb rejects the command.
310      * @throws ShellCommandUnresponsiveException in case the shell command doesn't send any output
311      *            for a period longer than <var>maxTimeToOutputResponse</var>.
312      * @throws IOException in case of I/O error on the connection.
313      *
314      * @see DdmPreferences#getTimeOut()
315      */
executeShellCommand(String command, IShellOutputReceiver receiver, int maxTimeToOutputResponse)316     public void executeShellCommand(String command, IShellOutputReceiver receiver,
317             int maxTimeToOutputResponse)
318             throws TimeoutException, AdbCommandRejectedException, ShellCommandUnresponsiveException,
319             IOException;
320 
321     /**
322      * Runs the event log service and outputs the event log to the {@link LogReceiver}.
323      * <p/>This call is blocking until {@link LogReceiver#isCancelled()} returns true.
324      * @param receiver the receiver to receive the event log entries.
325      * @throws TimeoutException in case of timeout on the connection. This can only be thrown if the
326      * timeout happens during setup. Once logs start being received, no timeout will occur as it's
327      * not possible to detect a difference between no log and timeout.
328      * @throws AdbCommandRejectedException if adb rejects the command
329      * @throws IOException in case of I/O error on the connection.
330      */
runEventLogService(LogReceiver receiver)331     public void runEventLogService(LogReceiver receiver)
332             throws TimeoutException, AdbCommandRejectedException, IOException;
333 
334     /**
335      * Runs the log service for the given log and outputs the log to the {@link LogReceiver}.
336      * <p/>This call is blocking until {@link LogReceiver#isCancelled()} returns true.
337      *
338      * @param logname the logname of the log to read from.
339      * @param receiver the receiver to receive the event log entries.
340      * @throws TimeoutException in case of timeout on the connection. This can only be thrown if the
341      *            timeout happens during setup. Once logs start being received, no timeout will
342      *            occur as it's not possible to detect a difference between no log and timeout.
343      * @throws AdbCommandRejectedException if adb rejects the command
344      * @throws IOException in case of I/O error on the connection.
345      */
runLogService(String logname, LogReceiver receiver)346     public void runLogService(String logname, LogReceiver receiver)
347             throws TimeoutException, AdbCommandRejectedException, IOException;
348 
349     /**
350      * Creates a port forwarding between a local and a remote port.
351      *
352      * @param localPort the local port to forward
353      * @param remotePort the remote port.
354      * @return <code>true</code> if success.
355      * @throws TimeoutException in case of timeout on the connection.
356      * @throws AdbCommandRejectedException if adb rejects the command
357      * @throws IOException in case of I/O error on the connection.
358      */
createForward(int localPort, int remotePort)359     public void createForward(int localPort, int remotePort)
360             throws TimeoutException, AdbCommandRejectedException, IOException;
361 
362     /**
363      * Creates a port forwarding between a local TCP port and a remote Unix Domain Socket.
364      *
365      * @param localPort the local port to forward
366      * @param remoteSocketName name of the unix domain socket created on the device
367      * @param namespace namespace in which the unix domain socket was created
368      * @return <code>true</code> if success.
369      * @throws TimeoutException in case of timeout on the connection.
370      * @throws AdbCommandRejectedException if adb rejects the command
371      * @throws IOException in case of I/O error on the connection.
372      */
createForward(int localPort, String remoteSocketName, DeviceUnixSocketNamespace namespace)373     public void createForward(int localPort, String remoteSocketName,
374             DeviceUnixSocketNamespace namespace)
375             throws TimeoutException, AdbCommandRejectedException, IOException;
376 
377     /**
378      * Removes a port forwarding between a local and a remote port.
379      *
380      * @param localPort the local port to forward
381      * @param remotePort the remote port.
382      * @return <code>true</code> if success.
383      * @throws TimeoutException in case of timeout on the connection.
384      * @throws AdbCommandRejectedException if adb rejects the command
385      * @throws IOException in case of I/O error on the connection.
386      */
removeForward(int localPort, int remotePort)387     public void removeForward(int localPort, int remotePort)
388             throws TimeoutException, AdbCommandRejectedException, IOException;
389 
390     /**
391      * Removes an existing port forwarding between a local and a remote port.
392      *
393      * @param localPort the local port to forward
394      * @param remoteSocketName the remote unix domain socket name.
395      * @param namespace namespace in which the unix domain socket was created
396      * @return <code>true</code> if success.
397      * @throws TimeoutException in case of timeout on the connection.
398      * @throws AdbCommandRejectedException if adb rejects the command
399      * @throws IOException in case of I/O error on the connection.
400      */
removeForward(int localPort, String remoteSocketName, DeviceUnixSocketNamespace namespace)401     public void removeForward(int localPort, String remoteSocketName,
402             DeviceUnixSocketNamespace namespace)
403             throws TimeoutException, AdbCommandRejectedException, IOException;
404 
405     /**
406      * Returns the name of the client by pid or <code>null</code> if pid is unknown
407      * @param pid the pid of the client.
408      */
getClientName(int pid)409     public String getClientName(int pid);
410 
411     /**
412      * Push a single file.
413      * @param local the local filepath.
414      * @param remote The remote filepath.
415      *
416      * @throws IOException in case of I/O error on the connection.
417      * @throws AdbCommandRejectedException if adb rejects the command
418      * @throws TimeoutException in case of a timeout reading responses from the device.
419      * @throws SyncException if file could not be pushed
420      */
pushFile(String local, String remote)421     public void pushFile(String local, String remote)
422             throws IOException, AdbCommandRejectedException, TimeoutException, SyncException;
423 
424     /**
425      * Pulls a single file.
426      *
427      * @param remote the full path to the remote file
428      * @param local The local destination.
429      *
430      * @throws IOException in case of an IO exception.
431      * @throws AdbCommandRejectedException if adb rejects the command
432      * @throws TimeoutException in case of a timeout reading responses from the device.
433      * @throws SyncException in case of a sync exception.
434      */
pullFile(String remote, String local)435     public void pullFile(String remote, String local)
436             throws IOException, AdbCommandRejectedException, TimeoutException, SyncException;
437 
438     /**
439      * Installs an Android application on device. This is a helper method that combines the
440      * syncPackageToDevice, installRemotePackage, and removePackage steps
441      *
442      * @param packageFilePath the absolute file system path to file on local host to install
443      * @param reinstall set to <code>true</code> if re-install of app should be performed
444      * @param extraArgs optional extra arguments to pass. See 'adb shell pm install --help' for
445      *            available options.
446      * @return a {@link String} with an error code, or <code>null</code> if success.
447      * @throws InstallException if the installation fails.
448      */
installPackage(String packageFilePath, boolean reinstall, String... extraArgs)449     public String installPackage(String packageFilePath, boolean reinstall, String... extraArgs)
450             throws InstallException;
451 
452     /**
453      * Pushes a file to device
454      *
455      * @param localFilePath the absolute path to file on local host
456      * @return {@link String} destination path on device for file
457      * @throws TimeoutException in case of timeout on the connection.
458      * @throws AdbCommandRejectedException if adb rejects the command
459      * @throws IOException in case of I/O error on the connection.
460      * @throws SyncException if an error happens during the push of the package on the device.
461      */
syncPackageToDevice(String localFilePath)462     public String syncPackageToDevice(String localFilePath)
463             throws TimeoutException, AdbCommandRejectedException, IOException, SyncException;
464 
465     /**
466      * Installs the application package that was pushed to a temporary location on the device.
467      *
468      * @param remoteFilePath absolute file path to package file on device
469      * @param reinstall set to <code>true</code> if re-install of app should be performed
470      * @param extraArgs optional extra arguments to pass. See 'adb shell pm install --help' for
471      *            available options.
472      * @throws InstallException if the installation fails.
473      */
installRemotePackage(String remoteFilePath, boolean reinstall, String... extraArgs)474     public String installRemotePackage(String remoteFilePath, boolean reinstall,
475             String... extraArgs) throws InstallException;
476 
477     /**
478      * Removes a file from device.
479      *
480      * @param remoteFilePath path on device of file to remove
481      * @throws InstallException if the installation fails.
482      */
removeRemotePackage(String remoteFilePath)483     public void removeRemotePackage(String remoteFilePath) throws InstallException;
484 
485     /**
486      * Uninstalls an package from the device.
487      *
488      * @param packageName the Android application package name to uninstall
489      * @return a {@link String} with an error code, or <code>null</code> if success.
490      * @throws InstallException if the uninstallation fails.
491      */
uninstallPackage(String packageName)492     public String uninstallPackage(String packageName) throws InstallException;
493 
494     /**
495      * Reboot the device.
496      *
497      * @param into the bootloader name to reboot into, or null to just reboot the device.
498      * @throws TimeoutException in case of timeout on the connection.
499      * @throws AdbCommandRejectedException if adb rejects the command
500      * @throws IOException
501      */
reboot(String into)502     public void reboot(String into)
503             throws TimeoutException, AdbCommandRejectedException, IOException;
504 
505     /**
506      * Return the device's battery level, from 0 to 100 percent.
507      * <p/>
508      * The battery level may be cached. Only queries the device for its
509      * battery level if 5 minutes have expired since the last successful query.
510      *
511      * @return the battery level or <code>null</code> if it could not be retrieved
512      */
getBatteryLevel()513     public Integer getBatteryLevel() throws TimeoutException,
514             AdbCommandRejectedException, IOException, ShellCommandUnresponsiveException;
515 
516     /**
517      * Return the device's battery level, from 0 to 100 percent.
518      * <p/>
519      * The battery level may be cached. Only queries the device for its
520      * battery level if <code>freshnessMs</code> ms have expired since the last successful query.
521      *
522      * @param freshnessMs
523      * @return the battery level or <code>null</code> if it could not be retrieved
524      * @throws ShellCommandUnresponsiveException
525      */
getBatteryLevel(long freshnessMs)526     public Integer getBatteryLevel(long freshnessMs) throws TimeoutException,
527             AdbCommandRejectedException, IOException, ShellCommandUnresponsiveException;
528 
529 }
530