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><build></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