1 /* 2 * Copyright (C) 2016 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 package com.android.tradefed.device; 17 18 import com.android.ddmlib.IDevice; 19 import com.android.ddmlib.IShellOutputReceiver; 20 import com.android.ddmlib.Log.LogLevel; 21 import com.android.ddmlib.testrunner.IRemoteAndroidTestRunner; 22 import com.android.tradefed.build.IBuildInfo; 23 import com.android.tradefed.command.remote.DeviceDescriptor; 24 import com.android.tradefed.device.ITestDevice.MountPointInfo; 25 import com.android.tradefed.device.ITestDevice.RecoveryMode; 26 import com.android.tradefed.log.ITestLogger; 27 import com.android.tradefed.result.ITestLifeCycleReceiver; 28 import com.android.tradefed.result.InputStreamSource; 29 import com.android.tradefed.targetprep.TargetSetupError; 30 import com.android.tradefed.util.Bugreport; 31 import com.android.tradefed.util.CommandResult; 32 import com.android.tradefed.util.ProcessInfo; 33 import com.android.tradefed.util.TimeUtil; 34 35 import com.google.errorprone.annotations.MustBeClosed; 36 37 import java.io.File; 38 import java.io.InputStream; 39 import java.io.OutputStream; 40 import java.util.Collection; 41 import java.util.Date; 42 import java.util.List; 43 import java.util.Set; 44 import java.util.concurrent.TimeUnit; 45 46 /** 47 * Provides an reliable and slightly higher level API to a ddmlib {@link IDevice}. 48 * <p/> 49 * Retries device commands for a configurable amount, and provides a device recovery 50 * interface for devices which are unresponsive. 51 */ 52 public interface INativeDevice { 53 54 /** 55 * Default value when API Level cannot be detected 56 */ 57 public final static int UNKNOWN_API_LEVEL = -1; 58 59 /** 60 * Set the {@link TestDeviceOptions} for the device 61 */ setOptions(TestDeviceOptions options)62 public void setOptions(TestDeviceOptions options); 63 64 /** 65 * Returns a reference to the associated ddmlib {@link IDevice}. 66 * <p/> 67 * A new {@link IDevice} may be allocated by DDMS each time the device disconnects and 68 * reconnects from adb. Thus callers should not keep a reference to the {@link IDevice}, 69 * because that reference may become stale. 70 * 71 * @return the {@link IDevice} 72 */ getIDevice()73 public IDevice getIDevice(); 74 75 /** 76 * Convenience method to get serial number of this device. 77 * 78 * @return the {@link String} serial number 79 */ getSerialNumber()80 public String getSerialNumber(); 81 82 /** 83 * Retrieve the given property value from the device. 84 * 85 * @param name the property name 86 * @return the property value or <code>null</code> if it does not exist 87 * @throws DeviceNotAvailableException 88 */ getProperty(String name)89 public String getProperty(String name) throws DeviceNotAvailableException; 90 91 /** 92 * Sets the given property value on the device. Requires adb root is true. 93 * 94 * @param propKey The key targeted to be set. 95 * @param propValue The property value to be set. 96 * @return returns <code>True</code> if the setprop command was successful, False otherwise. 97 * @throws DeviceNotAvailableException 98 */ setProperty(String propKey, String propValue)99 public boolean setProperty(String propKey, String propValue) throws DeviceNotAvailableException; 100 101 /** 102 * Convenience method to get the bootloader version of this device. 103 * <p/> 104 * Will attempt to retrieve bootloader version from the device's current state. (ie if device 105 * is in fastboot mode, it will attempt to retrieve version from fastboot) 106 * 107 * @return the {@link String} bootloader version or <code>null</code> if it cannot be found 108 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 109 * recovered. 110 */ getBootloaderVersion()111 public String getBootloaderVersion() throws DeviceNotAvailableException; 112 113 /** 114 * Convenience method to get baseband (radio) version of this device. Getting the radio version 115 * is device specific, so it might not return the correct information for all devices. This 116 * method relies on the gsm.version.baseband propery to return the correct version information. 117 * This is not accurate for some CDMA devices and the version returned here might not match 118 * the version reported from fastboot and might not return the version for the CDMA radio. 119 * TL;DR this method only reports accurate version if the gsm.version.baseband property is the 120 * same as the version returned by <code>fastboot getvar version-baseband</code>. 121 * 122 * @return the {@link String} baseband version or <code>null</code> if it cannot be determined 123 * (device has no radio or version string cannot be read) 124 * @throws DeviceNotAvailableException if the connection with the device is lost and cannot 125 * be recovered. 126 */ getBasebandVersion()127 public String getBasebandVersion() throws DeviceNotAvailableException; 128 129 /** 130 * Convenience method to get the product type of this device. 131 * <p/> 132 * This method will work if device is in either adb or fastboot mode. 133 * 134 * @return the {@link String} product type name. Will not be null 135 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 136 * recovered, or if product type can not be determined 137 */ getProductType()138 public String getProductType() throws DeviceNotAvailableException; 139 140 /** 141 * Convenience method to get the product variant of this device. 142 * <p/> 143 * This method will work if device is in either adb or fastboot mode. 144 * 145 * @return the {@link String} product variant name or <code>null</code> if it cannot be 146 * determined 147 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 148 * recovered. 149 */ getProductVariant()150 public String getProductVariant() throws DeviceNotAvailableException; 151 152 /** 153 * Convenience method to get the product type of this device when its in fastboot mode. 154 * <p/> 155 * This method should only be used if device should be in fastboot. Its a bit safer variant 156 * than the generic {@link #getProductType()} method in this case, because ITestDevice 157 * will know to recover device into fastboot if device is in incorrect state or is 158 * unresponsive. 159 * 160 * @return the {@link String} product type name or <code>null</code> if it cannot be determined 161 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 162 * recovered. 163 */ getFastbootProductType()164 public String getFastbootProductType() throws DeviceNotAvailableException; 165 166 /** 167 * Convenience method to get the product type of this device when its in fastboot mode. 168 * <p/> 169 * This method should only be used if device should be in fastboot. Its a bit safer variant 170 * than the generic {@link #getProductType()} method in this case, because ITestDevice 171 * will know to recover device into fastboot if device is in incorrect state or is 172 * unresponsive. 173 * 174 * @return the {@link String} product type name or <code>null</code> if it cannot be determined 175 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 176 * recovered. 177 */ getFastbootProductVariant()178 public String getFastbootProductVariant() throws DeviceNotAvailableException; 179 180 /** 181 * Retrieve the alias of the build that the device is currently running. 182 * 183 * <p>Build alias is usually a more readable string than build id (typically a number for 184 * Nexus builds). For example, final Android 4.2 release has build alias JDQ39, and build id 185 * 573038 186 * @return the build alias or fall back to build id if it could not be retrieved 187 * @throws DeviceNotAvailableException 188 */ getBuildAlias()189 public String getBuildAlias() throws DeviceNotAvailableException; 190 191 /** 192 * Retrieve the build the device is currently running. 193 * 194 * @return the build id or {@link IBuildInfo#UNKNOWN_BUILD_ID} if it could not be retrieved 195 * @throws DeviceNotAvailableException 196 */ getBuildId()197 public String getBuildId() throws DeviceNotAvailableException; 198 199 /** 200 * Retrieve the build flavor for the device. 201 * 202 * @return the build flavor or null if it could not be retrieved 203 * @throws DeviceNotAvailableException 204 */ getBuildFlavor()205 public String getBuildFlavor() throws DeviceNotAvailableException; 206 207 /** 208 * Executes the given adb shell command, retrying multiple times if command fails. 209 * <p/> 210 * A simpler form of 211 * {@link #executeShellCommand(String, IShellOutputReceiver, long, TimeUnit, int)} with 212 * default values. 213 * 214 * @param command the adb shell command to run 215 * @param receiver the {@link IShellOutputReceiver} to direct shell output to. 216 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 217 * recovered. 218 */ executeShellCommand(String command, IShellOutputReceiver receiver)219 public void executeShellCommand(String command, IShellOutputReceiver receiver) 220 throws DeviceNotAvailableException; 221 222 /** 223 * Executes a adb shell command, with more parameters to control command behavior. 224 * 225 * @see #executeShellCommand(String, IShellOutputReceiver) 226 * @param command the adb shell command to run 227 * @param receiver the {@link IShellOutputReceiver} to direct shell output to. 228 * @param maxTimeToOutputShellResponse the maximum amount of time during which the command is 229 * allowed to not output any response; unit as specified in <code>timeUnit</code> 230 * @param timeUnit unit for <code>maxTimeToOutputShellResponse</code> 231 * @param retryAttempts the maximum number of times to retry command if it fails due to a 232 * exception. DeviceNotResponsiveException will be thrown if <var>retryAttempts</var> 233 * are performed without success. 234 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 235 * recovered. 236 * @see TimeUtil 237 */ executeShellCommand(String command, IShellOutputReceiver receiver, long maxTimeToOutputShellResponse, TimeUnit timeUnit, int retryAttempts)238 public void executeShellCommand(String command, IShellOutputReceiver receiver, 239 long maxTimeToOutputShellResponse, TimeUnit timeUnit, int retryAttempts) 240 throws DeviceNotAvailableException; 241 242 /** 243 * Executes a adb shell command, with more parameters to control command behavior. 244 * 245 * @see #executeShellCommand(String, IShellOutputReceiver) 246 * @param command the adb shell command to run 247 * @param receiver the {@link IShellOutputReceiver} to direct shell output to. 248 * @param maxTimeoutForCommand the maximum timeout for the command to complete; unit as 249 * specified in <code>timeUnit</code> 250 * @param maxTimeToOutputShellResponse the maximum amount of time during which the command is 251 * allowed to not output any response; unit as specified in <code>timeUnit</code> 252 * @param timeUnit unit for <code>maxTimeToOutputShellResponse</code> 253 * @param retryAttempts the maximum number of times to retry command if it fails due to a 254 * exception. DeviceNotResponsiveException will be thrown if <var>retryAttempts</var> are 255 * performed without success. 256 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 257 * recovered. 258 * @see TimeUtil 259 */ executeShellCommand( String command, IShellOutputReceiver receiver, long maxTimeoutForCommand, long maxTimeToOutputShellResponse, TimeUnit timeUnit, int retryAttempts)260 public void executeShellCommand( 261 String command, 262 IShellOutputReceiver receiver, 263 long maxTimeoutForCommand, 264 long maxTimeToOutputShellResponse, 265 TimeUnit timeUnit, 266 int retryAttempts) 267 throws DeviceNotAvailableException; 268 269 /** 270 * Helper method which executes a adb shell command and returns output as a {@link String}. 271 * 272 * @param command the adb shell command to run 273 * @return the shell output 274 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 275 * recovered. 276 */ executeShellCommand(String command)277 public String executeShellCommand(String command) throws DeviceNotAvailableException; 278 279 /** 280 * Helper method which executes a adb shell command and returns the results as a {@link 281 * CommandResult} properly populated with the command status output, stdout and stderr. 282 * 283 * @param command The command that should be run. 284 * @return The result in {@link CommandResult}. 285 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 286 * recovered. 287 */ executeShellV2Command(String command)288 public CommandResult executeShellV2Command(String command) throws DeviceNotAvailableException; 289 290 /** 291 * Helper method which executes an adb shell command and returns the results as a {@link 292 * CommandResult} properly populated with the command status output, stdout and stderr. 293 * 294 * @param command The command that should be run. 295 * @param pipeAsInput A {@link File} that will be piped as input to the command. 296 * @return The result in {@link CommandResult}. 297 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 298 * recovered. 299 */ executeShellV2Command(String command, File pipeAsInput)300 public CommandResult executeShellV2Command(String command, File pipeAsInput) 301 throws DeviceNotAvailableException; 302 303 /** 304 * Helper method which executes an adb shell command and returns the results as a {@link 305 * CommandResult} properly populated with the command status output, stdout and stderr. 306 * 307 * @param command The command that should be run. 308 * @param pipeToOutput {@link OutputStream} where the std output will be redirected. 309 * @return The result in {@link CommandResult}. 310 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 311 * recovered. 312 */ executeShellV2Command(String command, OutputStream pipeToOutput)313 public CommandResult executeShellV2Command(String command, OutputStream pipeToOutput) 314 throws DeviceNotAvailableException; 315 316 /** 317 * Executes a adb shell command, with more parameters to control command behavior. 318 * 319 * @see #executeShellV2Command(String) 320 * @param command the adb shell command to run 321 * @param maxTimeoutForCommand the maximum timeout for the command to complete; unit as 322 * specified in <code>timeUnit</code> 323 * @param timeUnit unit for <code>maxTimeToOutputShellResponse</code> 324 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 325 * recovered. 326 * @see TimeUtil 327 */ executeShellV2Command( String command, final long maxTimeoutForCommand, final TimeUnit timeUnit)328 public CommandResult executeShellV2Command( 329 String command, final long maxTimeoutForCommand, final TimeUnit timeUnit) 330 throws DeviceNotAvailableException; 331 332 /** 333 * Executes a adb shell command, with more parameters to control command behavior. 334 * 335 * @see #executeShellV2Command(String) 336 * @param command the adb shell command to run 337 * @param maxTimeoutForCommand the maximum timeout for the command to complete; unit as 338 * specified in <code>timeUnit</code> 339 * @param timeUnit unit for <code>maxTimeToOutputShellResponse</code> 340 * @param retryAttempts the maximum number of times to retry command if it fails due to a 341 * exception. DeviceNotResponsiveException will be thrown if <var>retryAttempts</var> are 342 * performed without success. 343 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 344 * recovered. 345 * @see TimeUtil 346 */ executeShellV2Command( String command, final long maxTimeoutForCommand, final TimeUnit timeUnit, int retryAttempts)347 public CommandResult executeShellV2Command( 348 String command, 349 final long maxTimeoutForCommand, 350 final TimeUnit timeUnit, 351 int retryAttempts) 352 throws DeviceNotAvailableException; 353 354 /** 355 * Executes a adb shell command, with more parameters to control command behavior. 356 * 357 * @see #executeShellV2Command(String) 358 * @param command the adb shell command to run 359 * @param pipeAsInput A {@link File} that will be piped as input to the command. 360 * @param pipeToOutput {@link OutputStream} where the std output will be redirected. 361 * @param maxTimeoutForCommand the maximum timeout for the command to complete; unit as 362 * specified in <code>timeUnit</code> 363 * @param timeUnit unit for <code>maxTimeToOutputShellResponse</code> 364 * @param retryAttempts the maximum number of times to retry command if it fails due to a 365 * exception. DeviceNotResponsiveException will be thrown if <var>retryAttempts</var> are 366 * performed without success. 367 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 368 * recovered. 369 * @see TimeUtil 370 */ executeShellV2Command( String command, File pipeAsInput, OutputStream pipeToOutput, final long maxTimeoutForCommand, final TimeUnit timeUnit, int retryAttempts)371 public CommandResult executeShellV2Command( 372 String command, 373 File pipeAsInput, 374 OutputStream pipeToOutput, 375 final long maxTimeoutForCommand, 376 final TimeUnit timeUnit, 377 int retryAttempts) 378 throws DeviceNotAvailableException; 379 380 /** 381 * Helper method which executes a adb command as a system command. 382 * <p/> 383 * {@link #executeShellCommand(String)} should be used instead wherever possible, as that 384 * method provides better failure detection and performance. 385 * 386 * @param commandArgs the adb command and arguments to run 387 * @return the stdout from command. <code>null</code> if command failed to execute. 388 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 389 * recovered. 390 */ executeAdbCommand(String... commandArgs)391 public String executeAdbCommand(String... commandArgs) throws DeviceNotAvailableException; 392 393 /** 394 * Helper method which executes a fastboot command as a system command with a default timeout 395 * of 2 minutes. 396 * <p/> 397 * Expected to be used when device is already in fastboot mode. 398 * 399 * @param commandArgs the fastboot command and arguments to run 400 * @return the CommandResult containing output of command 401 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 402 * recovered. 403 */ executeFastbootCommand(String... commandArgs)404 public CommandResult executeFastbootCommand(String... commandArgs) 405 throws DeviceNotAvailableException; 406 407 /** 408 * Helper method which executes a fastboot command as a system command. 409 * <p/> 410 * Expected to be used when device is already in fastboot mode. 411 * 412 * @param timeout the time in milliseconds before the command expire 413 * @param commandArgs the fastboot command and arguments to run 414 * @return the CommandResult containing output of command 415 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 416 * recovered. 417 */ executeFastbootCommand(long timeout, String... commandArgs)418 public CommandResult executeFastbootCommand(long timeout, String... commandArgs) 419 throws DeviceNotAvailableException; 420 421 /** 422 * Helper method which executes a long running fastboot command as a system command. 423 * <p/> 424 * Identical to {@link #executeFastbootCommand(String...)} except uses a longer timeout. 425 * 426 * @param commandArgs the fastboot command and arguments to run 427 * @return the CommandResult containing output of command 428 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 429 * recovered. 430 */ executeLongFastbootCommand(String... commandArgs)431 public CommandResult executeLongFastbootCommand(String... commandArgs) 432 throws DeviceNotAvailableException; 433 434 /** 435 * Get whether to use fastboot erase or fastboot format to wipe a partition on the device. 436 * 437 * @return {@code true} if fastboot erase will be used or {@code false} if fastboot format will 438 * be used. 439 * @see #fastbootWipePartition(String) 440 */ getUseFastbootErase()441 public boolean getUseFastbootErase(); 442 443 /** 444 * Set whether to use fastboot erase or fastboot format to wipe a partition on the device. 445 * 446 * @param useFastbootErase {@code true} if fastboot erase should be used or {@code false} if 447 * fastboot format should be used. 448 * @see #fastbootWipePartition(String) 449 */ setUseFastbootErase(boolean useFastbootErase)450 public void setUseFastbootErase(boolean useFastbootErase); 451 452 /** 453 * Helper method which wipes a partition for the device. 454 * <p/> 455 * If {@link #getUseFastbootErase()} is {@code true}, then fastboot erase will be used to wipe 456 * the partition. The device must then create a filesystem the next time the device boots. 457 * Otherwise, fastboot format is used which will create a new filesystem on the device. 458 * <p/> 459 * Expected to be used when device is already in fastboot mode. 460 * 461 * @param partition the partition to wipe 462 * @return the CommandResult containing output of command 463 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 464 * recovered. 465 */ fastbootWipePartition(String partition)466 public CommandResult fastbootWipePartition(String partition) throws DeviceNotAvailableException; 467 468 /** 469 * Runs instrumentation tests, and provides device recovery. 470 * 471 * <p>If connection with device is lost before test run completes, and recovery succeeds, all 472 * listeners will be informed of testRunFailed and "false" will be returned. The test command 473 * will not be rerun. It is left to callers to retry if necessary. 474 * 475 * <p>If connection with device is lost before test run completes, and recovery fails, all 476 * listeners will be informed of testRunFailed and DeviceNotAvailableException will be thrown. 477 * 478 * @param runner the {@link IRemoteAndroidTestRunner} which runs the tests 479 * @param listeners the test result listeners 480 * @return <code>true</code> if test command completed. <code>false</code> if it failed to 481 * complete due to device communication exception, but recovery succeeded 482 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 483 * recovered. ie test command failed to complete and recovery failed. 484 */ runInstrumentationTests( IRemoteAndroidTestRunner runner, Collection<ITestLifeCycleReceiver> listeners)485 public boolean runInstrumentationTests( 486 IRemoteAndroidTestRunner runner, Collection<ITestLifeCycleReceiver> listeners) 487 throws DeviceNotAvailableException; 488 489 /** 490 * Convenience method for performing {@link #runInstrumentationTests(IRemoteAndroidTestRunner, 491 * Collection)} with one or more listeners passed as parameters. 492 * 493 * @param runner the {@link IRemoteAndroidTestRunner} which runs the tests 494 * @param listeners the test result listener(s) 495 * @return <code>true</code> if test command completed. <code>false</code> if it failed to 496 * complete, but recovery succeeded 497 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 498 * recovered. ie test command failed to complete and recovery failed. 499 */ runInstrumentationTests( IRemoteAndroidTestRunner runner, ITestLifeCycleReceiver... listeners)500 public boolean runInstrumentationTests( 501 IRemoteAndroidTestRunner runner, ITestLifeCycleReceiver... listeners) 502 throws DeviceNotAvailableException; 503 504 /** 505 * Same as {@link ITestDevice#runInstrumentationTests(IRemoteAndroidTestRunner, Collection)} but 506 * runs the test for the given user. 507 */ runInstrumentationTestsAsUser( IRemoteAndroidTestRunner runner, int userId, Collection<ITestLifeCycleReceiver> listeners)508 public boolean runInstrumentationTestsAsUser( 509 IRemoteAndroidTestRunner runner, 510 int userId, 511 Collection<ITestLifeCycleReceiver> listeners) 512 throws DeviceNotAvailableException; 513 514 /** 515 * Same as {@link ITestDevice#runInstrumentationTests(IRemoteAndroidTestRunner, 516 * ITestLifeCycleReceiver...)} but runs the test for a given user. 517 */ runInstrumentationTestsAsUser( IRemoteAndroidTestRunner runner, int userId, ITestLifeCycleReceiver... listeners)518 public boolean runInstrumentationTestsAsUser( 519 IRemoteAndroidTestRunner runner, int userId, ITestLifeCycleReceiver... listeners) 520 throws DeviceNotAvailableException; 521 522 /** 523 * Check whether platform on device supports runtime permission granting 524 * @return True if runtime permission are supported, false otherwise. 525 * @throws DeviceNotAvailableException 526 */ isRuntimePermissionSupported()527 public boolean isRuntimePermissionSupported() throws DeviceNotAvailableException; 528 529 /** 530 * Retrieves a file off device. 531 * 532 * @param remoteFilePath the absolute path to file on device. 533 * @param localFile the local file to store contents in. If non-empty, contents will be 534 * replaced. 535 * @return <code>true</code> if file was retrieved successfully. <code>false</code> otherwise. 536 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 537 * recovered. 538 */ pullFile(String remoteFilePath, File localFile)539 public boolean pullFile(String remoteFilePath, File localFile) 540 throws DeviceNotAvailableException; 541 542 /** 543 * Retrieves a file off device, stores it in a local temporary {@link File}, and returns that 544 * {@code File}. 545 * 546 * @param remoteFilePath the absolute path to file on device. 547 * @return A {@link File} containing the contents of the device file, or {@code null} if the 548 * copy failed for any reason (including problems with the host filesystem) 549 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 550 * recovered. 551 */ pullFile(String remoteFilePath)552 public File pullFile(String remoteFilePath) throws DeviceNotAvailableException; 553 554 /** 555 * Retrieves a file off device, and returns the contents. 556 * 557 * @param remoteFilePath the absolute path to file on device. 558 * @return A {@link String} containing the contents of the device file, or {@code null} if the 559 * copy failed for any reason (including problems with the host filesystem) 560 */ pullFileContents(String remoteFilePath)561 public String pullFileContents(String remoteFilePath) throws DeviceNotAvailableException; 562 563 /** 564 * A convenience method to retrieve a file from the device's external storage, stores it in a 565 * local temporary {@link File}, and return a reference to that {@code File}. 566 * 567 * @param remoteFilePath the path to file on device, relative to the device's external storage 568 * mountpoint 569 * @return A {@link File} containing the contents of the device file, or {@code null} if the 570 * copy failed for any reason (including problems with the host filesystem) 571 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 572 * recovered. 573 */ pullFileFromExternal(String remoteFilePath)574 public File pullFileFromExternal(String remoteFilePath) throws DeviceNotAvailableException; 575 576 /** 577 * Recursively pull directory contents from device. 578 * 579 * @param deviceFilePath the absolute file path of the remote source 580 * @param localDir the local directory to pull files into 581 * @return <code>true</code> if file was pulled successfully. <code>false</code> otherwise. 582 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 583 * recovered. 584 */ pullDir(String deviceFilePath, File localDir)585 public boolean pullDir(String deviceFilePath, File localDir) 586 throws DeviceNotAvailableException; 587 588 /** 589 * Push a file to device 590 * 591 * @param localFile the local file to push 592 * @param deviceFilePath the remote destination absolute file path 593 * @return <code>true</code> if file was pushed successfully. <code>false</code> otherwise. 594 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 595 * recovered. 596 */ pushFile(File localFile, String deviceFilePath)597 public boolean pushFile(File localFile, String deviceFilePath) 598 throws DeviceNotAvailableException; 599 600 /** 601 * Push file created from a string to device 602 * 603 * @param contents the contents of the file to push 604 * @param deviceFilePath the remote destination absolute file path 605 * @return <code>true</code> if string was pushed successfully. <code>false</code> otherwise. 606 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 607 * recovered. 608 */ pushString(String contents, String deviceFilePath)609 public boolean pushString(String contents, String deviceFilePath) 610 throws DeviceNotAvailableException; 611 612 /** 613 * Recursively push directory contents to device. 614 * 615 * @param localDir the local directory to push 616 * @param deviceFilePath the absolute file path of the remote destination 617 * @return <code>true</code> if file was pushed successfully. <code>false</code> otherwise. 618 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 619 * recovered. 620 */ pushDir(File localDir, String deviceFilePath)621 public boolean pushDir(File localDir, String deviceFilePath) 622 throws DeviceNotAvailableException; 623 624 /** 625 * Recursively push directory contents to device while excluding some directories that are 626 * filtered. 627 * 628 * @param localDir the local directory to push 629 * @param deviceFilePath the absolute file path of the remote destination 630 * @param excludedDirectories Set of excluded directories names that shouldn't be pushed. 631 * @return <code>true</code> if file was pushed successfully. <code>false</code> otherwise. 632 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 633 * recovered. 634 */ pushDir(File localDir, String deviceFilePath, Set<String> excludedDirectories)635 public boolean pushDir(File localDir, String deviceFilePath, Set<String> excludedDirectories) 636 throws DeviceNotAvailableException; 637 638 /** 639 * Incrementally syncs the contents of a local file directory to device. 640 * <p/> 641 * Decides which files to push by comparing timestamps of local files with their remote 642 * equivalents. Only 'newer' or non-existent files will be pushed to device. Thus overhead 643 * should be relatively small if file set on device is already up to date. 644 * <p/> 645 * Hidden files (with names starting with ".") will be ignored. 646 * <p/> 647 * Example usage: syncFiles("/tmp/files", "/sdcard") will created a /sdcard/files directory if 648 * it doesn't already exist, and recursively push the /tmp/files contents to /sdcard/files. 649 * 650 * @param localFileDir the local file directory containing files to recursively push. 651 * @param deviceFilePath the remote destination absolute file path root. All directories in thos 652 * file path must be readable. ie pushing to /data/local/tmp when adb is not root 653 * will fail 654 * @return <code>true</code> if files were synced successfully. <code>false</code> otherwise. 655 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 656 * recovered. 657 */ syncFiles(File localFileDir, String deviceFilePath)658 public boolean syncFiles(File localFileDir, String deviceFilePath) 659 throws DeviceNotAvailableException; 660 661 /** 662 * Helper method to determine if file on device exists. 663 * 664 * @param deviceFilePath the absolute path of file on device to check 665 * @return <code>true</code> if file exists, <code>false</code> otherwise. 666 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 667 * recovered. 668 */ doesFileExist(String deviceFilePath)669 public boolean doesFileExist(String deviceFilePath) throws DeviceNotAvailableException; 670 671 /** 672 * Helper method to delete a file or directory on the device. 673 * 674 * @param deviceFilePath The absolute path of the file on the device. 675 * @throws DeviceNotAvailableException 676 */ deleteFile(String deviceFilePath)677 public void deleteFile(String deviceFilePath) throws DeviceNotAvailableException; 678 679 /** 680 * Retrieve a reference to a remote file on device. 681 * 682 * @param path the file path to retrieve. Can be an absolute path or path relative to '/'. (ie 683 * both "/system" and "system" syntax is supported) 684 * @return the {@link IFileEntry} or <code>null</code> if file at given <var>path</var> cannot 685 * be found 686 * @throws DeviceNotAvailableException 687 */ getFileEntry(String path)688 public IFileEntry getFileEntry(String path) throws DeviceNotAvailableException; 689 690 /** 691 * Returns True if the file path on the device is an executable file, false otherwise. 692 * 693 * @throws DeviceNotAvailableException 694 */ isExecutable(String fullPath)695 public boolean isExecutable(String fullPath) throws DeviceNotAvailableException; 696 697 /** 698 * Return True if the path on the device is a directory, false otherwise. 699 * 700 * @throws DeviceNotAvailableException 701 */ isDirectory(String deviceFilePath)702 public boolean isDirectory(String deviceFilePath) throws DeviceNotAvailableException; 703 704 /** 705 * Alternative to using {@link IFileEntry} that sometimes won't work because of permissions. 706 * 707 * @param deviceFilePath is the path on the device where to do the search 708 * @return Array of string containing all the file in a path on the device. 709 * @throws DeviceNotAvailableException 710 */ getChildren(String deviceFilePath)711 public String[] getChildren(String deviceFilePath) throws DeviceNotAvailableException; 712 713 /** 714 * Helper method to determine amount of free space on device external storage. 715 * 716 * @return the amount of free space in KB 717 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 718 * recovered. 719 */ getExternalStoreFreeSpace()720 public long getExternalStoreFreeSpace() throws DeviceNotAvailableException; 721 722 /** 723 * Helper method to determine amount of free space on device partition. 724 * 725 * @return the amount of free space in KB 726 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 727 * recovered. 728 */ getPartitionFreeSpace(String partition)729 public long getPartitionFreeSpace(String partition) throws DeviceNotAvailableException; 730 731 /** 732 * Returns a mount point. 733 * <p/> 734 * Queries the device directly if the cached info in {@link IDevice} is not available. 735 * <p/> 736 * TODO: move this behavior to {@link IDevice#getMountPoint(String)} 737 * 738 * @param mountName the name of the mount point 739 * @return the mount point or <code>null</code> 740 * @see IDevice#getMountPoint(String) 741 */ getMountPoint(String mountName)742 public String getMountPoint(String mountName); 743 744 /** 745 * Returns a parsed version of the information in /proc/mounts on the device 746 * 747 * @return A {@link List} of {@link MountPointInfo} containing the information in "/proc/mounts" 748 */ getMountPointInfo()749 public List<MountPointInfo> getMountPointInfo() throws DeviceNotAvailableException; 750 751 /** 752 * Returns a {@link MountPointInfo} corresponding to the specified mountpoint path, or 753 * <code>null</code> if that path has nothing mounted or otherwise does not appear in 754 * /proc/mounts as a mountpoint. 755 * 756 * @return A {@link List} of {@link MountPointInfo} containing the information in "/proc/mounts" 757 * @see #getMountPointInfo() 758 */ getMountPointInfo(String mountpoint)759 public MountPointInfo getMountPointInfo(String mountpoint) throws DeviceNotAvailableException; 760 761 /** 762 * Start capturing logcat output from device in the background. 763 * <p/> 764 * Will have no effect if logcat output is already being captured. 765 * Data can be later retrieved via getLogcat. 766 * <p/> 767 * When the device is no longer in use, {@link #stopLogcat()} must be called. 768 * <p/> 769 * {@link #startLogcat()} and {@link #stopLogcat()} do not normally need to be called when 770 * within a TF invocation context, as the TF framework will start and stop logcat. 771 */ startLogcat()772 public void startLogcat(); 773 774 /** 775 * Stop capturing logcat output from device, and discard currently saved logcat data. 776 * <p/> 777 * Will have no effect if logcat output is not being captured. 778 */ stopLogcat()779 public void stopLogcat(); 780 781 /** 782 * Deletes any accumulated logcat data. 783 * <p/> 784 * This is useful for cases when you want to ensure {@link ITestDevice#getLogcat()} only returns 785 * log data produced after a certain point (such as after flashing a new device build, etc). 786 */ clearLogcat()787 public void clearLogcat(); 788 789 /** 790 * Grabs a snapshot stream of the logcat data. 791 * 792 * <p>Works in two modes: 793 * <li>If the logcat is currently being captured in the background, will return up to {@link 794 * TestDeviceOptions#getMaxLogcatDataSize()} bytes of the current contents of the background 795 * logcat capture 796 * <li>Otherwise, will return a static dump of the logcat data if device is currently responding 797 */ 798 @MustBeClosed getLogcat()799 public InputStreamSource getLogcat(); 800 801 /** 802 * Grabs a snapshot stream of captured logcat data starting the date provided. The time on the 803 * device should be used {@link #getDeviceDate}. 804 * 805 * <p> 806 * 807 * @param date in millisecond since epoch format of when to start the snapshot until present. 808 * (can be be obtained using 'date +%s') 809 */ 810 @MustBeClosed getLogcatSince(long date)811 public InputStreamSource getLogcatSince(long date); 812 813 /** 814 * Grabs a snapshot stream of the last <code>maxBytes</code> of captured logcat data. 815 * 816 * <p>Useful for cases when you want to capture frequent snapshots of the captured logcat data 817 * without incurring the potentially big disk space penalty of getting the entire {@link 818 * #getLogcat()} snapshot. 819 * 820 * @param maxBytes the maximum amount of data to return. Should be an amount that can 821 * comfortably fit in memory 822 */ 823 @MustBeClosed getLogcat(int maxBytes)824 public InputStreamSource getLogcat(int maxBytes); 825 826 /** 827 * Get a dump of the current logcat for device. Unlike {@link #getLogcat()}, this method will 828 * always return a static dump of the logcat. 829 * 830 * <p>Has the disadvantage that nothing will be returned if device is not reachable. 831 * 832 * @return a {@link InputStreamSource} of the logcat data. An empty stream is returned if fail 833 * to capture logcat data. 834 */ 835 @MustBeClosed getLogcatDump()836 public InputStreamSource getLogcatDump(); 837 838 /** 839 * Perform instructions to configure device for testing that after every boot. 840 * <p/> 841 * Should be called after device is fully booted/available 842 * <p/> 843 * In normal circumstances this method doesn't need to be called explicitly, as 844 * implementations should perform these steps automatically when performing a reboot. 845 * <p/> 846 * Where it may need to be called is when device reboots due to other events (eg when a 847 * fastboot update command has completed) 848 * 849 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 850 * recovered. 851 */ postBootSetup()852 public void postBootSetup() throws DeviceNotAvailableException; 853 854 /** 855 * Reboots the device into bootloader mode. 856 * <p/> 857 * Blocks until device is in bootloader mode. 858 * 859 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 860 * recovered. 861 */ rebootIntoBootloader()862 public void rebootIntoBootloader() throws DeviceNotAvailableException; 863 864 /** 865 * Reboots the device into adb mode. 866 * <p/> 867 * Blocks until device becomes available. 868 * 869 * @throws DeviceNotAvailableException if device is not available after reboot 870 */ reboot()871 public void reboot() throws DeviceNotAvailableException; 872 873 /** 874 * Reboots the device into adb recovery mode. 875 * <p/> 876 * Blocks until device enters recovery 877 * 878 * @throws DeviceNotAvailableException if device is not available after reboot 879 */ rebootIntoRecovery()880 public void rebootIntoRecovery() throws DeviceNotAvailableException; 881 882 /** 883 * An alternate to {@link #reboot()} that only blocks until device is online ie visible to adb. 884 * 885 * @throws DeviceNotAvailableException if device is not available after reboot 886 */ rebootUntilOnline()887 public void rebootUntilOnline() throws DeviceNotAvailableException; 888 889 /** 890 * Issues a command to reboot device and returns on command complete and when device is no 891 * longer visible to adb. 892 * 893 * @throws DeviceNotAvailableException 894 */ nonBlockingReboot()895 public void nonBlockingReboot() throws DeviceNotAvailableException; 896 897 /** 898 * Turns on adb root. If the "enable-root" setting is "false", will log a message and 899 * return without enabling root. 900 * <p/> 901 * Enabling adb root may cause device to disconnect from adb. This method will block until 902 * device is available. 903 * 904 * @return <code>true</code> if successful. 905 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 906 * recovered. 907 */ enableAdbRoot()908 public boolean enableAdbRoot() throws DeviceNotAvailableException; 909 910 /** 911 * Turns off adb root. 912 * <p/> 913 * Disabling adb root may cause device to disconnect from adb. This method will block until 914 * device is available. 915 * 916 * @return <code>true</code> if successful. 917 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 918 * recovered. 919 */ disableAdbRoot()920 public boolean disableAdbRoot() throws DeviceNotAvailableException; 921 922 /** 923 * @return <code>true</code> if device currently has adb root, <code>false</code> otherwise. 924 * 925 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 926 * recovered. 927 */ isAdbRoot()928 public boolean isAdbRoot() throws DeviceNotAvailableException; 929 930 /** 931 * Encrypts the device. 932 * <p/> 933 * Encrypting the device may be done inplace or with a wipe. Inplace encryption will not wipe 934 * any data on the device but normally takes a couple orders of magnitude longer than the wipe. 935 * <p/> 936 * This method will reboot the device if it is not already encrypted and will block until device 937 * is online. Also, it will not decrypt the device after the reboot. Therefore, the device 938 * might not be fully booted and/or ready to be tested when this method returns. 939 * 940 * @param inplace if the encryption process should take inplace and the device should not be 941 * wiped. 942 * @return <code>true</code> if successful. 943 * @throws DeviceNotAvailableException if device is not available after reboot. 944 * @throws UnsupportedOperationException if encryption is not supported on the device. 945 */ encryptDevice(boolean inplace)946 public boolean encryptDevice(boolean inplace) throws DeviceNotAvailableException, 947 UnsupportedOperationException; 948 949 /** 950 * Unencrypts the device. 951 * <p/> 952 * Unencrypting the device may cause device to be wiped and may reboot device. This method will 953 * block until device is available and ready for testing. Requires fastboot inorder to wipe the 954 * userdata partition. 955 * 956 * @return <code>true</code> if successful. 957 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 958 * recovered. 959 * @throws UnsupportedOperationException if encryption is not supported on the device. 960 */ unencryptDevice()961 public boolean unencryptDevice() throws DeviceNotAvailableException, 962 UnsupportedOperationException; 963 964 /** 965 * Unlocks the device if the device is in an encrypted state. 966 * </p> 967 * This method may restart the framework but will not call {@link #postBootSetup()}. Therefore, 968 * the device might not be fully ready to be tested when this method returns. 969 * 970 * @return <code>true</code> if successful or if the device is unencrypted. 971 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 972 * recovered. 973 * @throws UnsupportedOperationException if encryption is not supported on the device. 974 */ unlockDevice()975 public boolean unlockDevice() throws DeviceNotAvailableException, 976 UnsupportedOperationException; 977 978 /** 979 * Returns if the device is encrypted. 980 * 981 * @return <code>true</code> if the device is encrypted. 982 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 983 * recovered. 984 */ isDeviceEncrypted()985 public boolean isDeviceEncrypted() throws DeviceNotAvailableException; 986 987 /** 988 * Returns if encryption is supported on the device. 989 * 990 * @return <code>true</code> if the device supports encryption. 991 * @throws DeviceNotAvailableException 992 */ isEncryptionSupported()993 public boolean isEncryptionSupported() throws DeviceNotAvailableException; 994 995 /** 996 * Waits for the device to be responsive and available for testing. 997 * 998 * @param waitTime the time in ms to wait 999 * @throws DeviceNotAvailableException if device is still unresponsive after waitTime expires. 1000 */ waitForDeviceAvailable(final long waitTime)1001 public void waitForDeviceAvailable(final long waitTime) throws DeviceNotAvailableException; 1002 1003 /** 1004 * Waits for the device to be responsive and available for testing. Uses default timeout. 1005 * 1006 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 1007 * recovered. 1008 */ waitForDeviceAvailable()1009 public void waitForDeviceAvailable() throws DeviceNotAvailableException; 1010 1011 /** 1012 * Blocks until device is visible via adb. 1013 * <p/> 1014 * Note the device may not necessarily be responsive to commands on completion. Use 1015 * {@link #waitForDeviceAvailable()} instead. 1016 * 1017 * @param waitTime the time in ms to wait 1018 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 1019 * recovered. 1020 */ waitForDeviceOnline(final long waitTime)1021 public void waitForDeviceOnline(final long waitTime) throws DeviceNotAvailableException; 1022 1023 /** 1024 * Blocks until device is visible via adb. Uses default timeout 1025 * <p/> 1026 * Note the device may not necessarily be responsive to commands on completion. Use 1027 * {@link #waitForDeviceAvailable()} instead. 1028 * 1029 * @throws DeviceNotAvailableException if connection with device is lost and cannot be 1030 * recovered. 1031 */ waitForDeviceOnline()1032 public void waitForDeviceOnline() throws DeviceNotAvailableException; 1033 1034 /** 1035 * Blocks for the device to be not available ie missing from adb 1036 * 1037 * @param waitTime the time in ms to wait 1038 * @return <code>true</code> if device becomes not available before time expires. 1039 * <code>false</code> otherwise 1040 */ waitForDeviceNotAvailable(final long waitTime)1041 public boolean waitForDeviceNotAvailable(final long waitTime); 1042 1043 /** 1044 * Blocks for the device to be in the 'adb recovery' state (note this is distinct from 1045 * {@link IDeviceRecovery}). 1046 * 1047 * @param waitTime the time in ms to wait 1048 * @return <code>true</code> if device boots into recovery before time expires. 1049 * <code>false</code> otherwise 1050 */ waitForDeviceInRecovery(final long waitTime)1051 public boolean waitForDeviceInRecovery(final long waitTime); 1052 1053 /** 1054 * Waits for device to be responsive to a basic adb shell command. 1055 * 1056 * @param waitTime the time in ms to wait 1057 * @return <code>true</code> if device becomes responsive before <var>waitTime</var> elapses. 1058 */ waitForDeviceShell(final long waitTime)1059 public boolean waitForDeviceShell(final long waitTime); 1060 1061 /** 1062 * Blocks until the device's boot complete flag is set. 1063 * 1064 * @param timeOut time in msecs to wait for the flag to be set 1065 * @return true if device's boot complete flag is set within the timeout 1066 * @throws DeviceNotAvailableException 1067 */ waitForBootComplete(long timeOut)1068 public boolean waitForBootComplete(long timeOut) throws DeviceNotAvailableException; 1069 1070 /** 1071 * Set the {@link IDeviceRecovery} to use for this device. Should be set when device is first 1072 * allocated. 1073 * 1074 * @param recovery the {@link IDeviceRecovery} 1075 */ setRecovery(IDeviceRecovery recovery)1076 public void setRecovery(IDeviceRecovery recovery); 1077 1078 /** 1079 * Set the current recovery mode to use for the device. 1080 * <p/> 1081 * Used to control what recovery method to use when a device communication problem is 1082 * encountered. Its recommended to only use this method sparingly when needed (for example, 1083 * when framework is down, etc 1084 * 1085 * @param mode whether 'recover till online only' mode should be on or not. 1086 */ setRecoveryMode(RecoveryMode mode)1087 public void setRecoveryMode(RecoveryMode mode); 1088 1089 /** 1090 * Get the current recovery mode used for the device. 1091 * 1092 * @return the current recovery mode used for the device. 1093 */ getRecoveryMode()1094 public RecoveryMode getRecoveryMode(); 1095 1096 /** 1097 * Get the device's state. 1098 */ getDeviceState()1099 public TestDeviceState getDeviceState(); 1100 1101 /** 1102 * @return <code>true</code> if device is connected to adb-over-tcp, <code>false</code> 1103 * otherwise. 1104 */ isAdbTcp()1105 public boolean isAdbTcp(); 1106 1107 /** 1108 * Switch device to adb-over-tcp mode. 1109 * 1110 * @return the tcp serial number or <code>null</code> if device could not be switched 1111 * @throws DeviceNotAvailableException 1112 */ switchToAdbTcp()1113 public String switchToAdbTcp() throws DeviceNotAvailableException; 1114 1115 /** 1116 * Switch device to adb over usb mode. 1117 * 1118 * @return <code>true</code> if switch was successful, <code>false</code> otherwise. 1119 * @throws DeviceNotAvailableException 1120 */ switchToAdbUsb()1121 public boolean switchToAdbUsb() throws DeviceNotAvailableException; 1122 1123 /** 1124 * Get the stream of emulator stdout and stderr 1125 * @return emulator output 1126 */ getEmulatorOutput()1127 public InputStreamSource getEmulatorOutput(); 1128 1129 /** 1130 * Close and delete the emulator output. 1131 */ stopEmulatorOutput()1132 public void stopEmulatorOutput(); 1133 1134 /** 1135 * Get the device API Level. Defaults to {@link #UNKNOWN_API_LEVEL}. 1136 * 1137 * @return an integer indicating the API Level of device 1138 * @throws DeviceNotAvailableException 1139 */ getApiLevel()1140 public int getApiLevel() throws DeviceNotAvailableException; 1141 1142 /** 1143 * Check whether or not a feature is currently supported given a minimally supported level. This 1144 * method takes into account unreleased features yet, before API level is raised. 1145 * 1146 * @param strictMinLevel The strict min possible level that supports the feature. 1147 * @return True if the level is supported. False otherwise. 1148 * @throws DeviceNotAvailableException 1149 */ checkApiLevelAgainstNextRelease(int strictMinLevel)1150 public boolean checkApiLevelAgainstNextRelease(int strictMinLevel) 1151 throws DeviceNotAvailableException; 1152 1153 /** 1154 * Helper to get the time difference between the device and a given {@link Date}. Use Epoch time 1155 * internally. 1156 * 1157 * @return the difference in milliseconds 1158 */ getDeviceTimeOffset(Date date)1159 public long getDeviceTimeOffset(Date date) throws DeviceNotAvailableException; 1160 1161 /** 1162 * Sets the date on device 1163 * <p> 1164 * Note: setting date on device requires root 1165 * @param date specify a particular date; will use host date if <code>null</code> 1166 * @throws DeviceNotAvailableException 1167 */ setDate(Date date)1168 public void setDate(Date date) throws DeviceNotAvailableException; 1169 1170 /** 1171 * Return the date of the device in millisecond since epoch. 1172 * 1173 * <p> 1174 * 1175 * @return the date of the device in epoch format. 1176 * @throws DeviceNotAvailableException 1177 */ getDeviceDate()1178 public long getDeviceDate() throws DeviceNotAvailableException; 1179 1180 /** 1181 * Make the system partition on the device writable. May reboot the device. 1182 * @throws DeviceNotAvailableException 1183 */ remountSystemWritable()1184 public void remountSystemWritable() throws DeviceNotAvailableException; 1185 1186 /** 1187 * Returns the key type used to sign the device image 1188 * <p> 1189 * Typically Android devices may be signed with test-keys (like in AOSP) or release-keys 1190 * (controlled by individual device manufacturers) 1191 * @return The signing key if found, null otherwise. 1192 * @throws DeviceNotAvailableException 1193 */ getBuildSigningKeys()1194 public String getBuildSigningKeys() throws DeviceNotAvailableException; 1195 1196 /** 1197 * Retrieves a bugreport from the device. 1198 * <p/> 1199 * The implementation of this is guaranteed to continue to work on a device without an sdcard 1200 * (or where the sdcard is not yet mounted). 1201 * 1202 * @return An {@link InputStreamSource} which will produce the bugreport contents on demand. In 1203 * case of failure, the {@code InputStreamSource} will produce an empty 1204 * {@link InputStream}. 1205 */ getBugreport()1206 public InputStreamSource getBugreport(); 1207 1208 /** 1209 * Retrieves a bugreportz from the device. Zip format bugreport contains the main bugreport 1210 * and other log files that are useful for debugging. 1211 * <p/> 1212 * Only supported for 'adb version' > 1.0.36 1213 * 1214 * @return a {@link InputStreamSource} of the zip file containing the bugreportz, return null 1215 * in case of failure. 1216 */ getBugreportz()1217 public InputStreamSource getBugreportz(); 1218 1219 /** 1220 * Helper method to take a bugreport and log it to the reporters. 1221 * 1222 * @param dataName name under which the bugreport will be reported. 1223 * @param listener an {@link ITestLogger} to log the bugreport. 1224 * @return True if the logging was successful, false otherwise. 1225 */ logBugreport(String dataName, ITestLogger listener)1226 public boolean logBugreport(String dataName, ITestLogger listener); 1227 1228 /** 1229 * Take a bugreport and returns it inside a {@link Bugreport} object to handle it. Return null 1230 * in case of issue. 1231 * </p> 1232 * File referenced in the Bugreport object need to be cleaned via {@link Bugreport#close()}. 1233 */ takeBugreport()1234 public Bugreport takeBugreport(); 1235 1236 /** 1237 * Get the device class. 1238 * 1239 * @return the {@link String} device class. 1240 */ getDeviceClass()1241 public String getDeviceClass(); 1242 1243 /** 1244 * Extra steps for device specific required setup that will be executed on the device prior 1245 * to the invocation flow. 1246 */ preInvocationSetup(IBuildInfo info)1247 public void preInvocationSetup(IBuildInfo info) 1248 throws TargetSetupError, DeviceNotAvailableException; 1249 1250 /** 1251 * Extra steps for device specific required setup that will be executed on the device prior to 1252 * the invocation flow. 1253 */ preInvocationSetup(IBuildInfo info, List<IBuildInfo> testResourceBuildInfos)1254 public default void preInvocationSetup(IBuildInfo info, List<IBuildInfo> testResourceBuildInfos) 1255 throws TargetSetupError, DeviceNotAvailableException { 1256 preInvocationSetup(info); 1257 } 1258 1259 /** 1260 * Extra steps for device specific required clean up that will be executed after the invocation 1261 * is done. 1262 */ postInvocationTearDown()1263 public void postInvocationTearDown(); 1264 1265 /** 1266 * Return true if the device is headless (no screen), false otherwise. 1267 */ isHeadless()1268 public boolean isHeadless() throws DeviceNotAvailableException; 1269 1270 /** 1271 * Return a {@link DeviceDescriptor} from the device information to get info on it without 1272 * passing the actual device object. 1273 */ getDeviceDescriptor()1274 public DeviceDescriptor getDeviceDescriptor(); 1275 1276 /** 1277 * Helper method runs the "ps" command and returns list of USER, PID and NAME of all the 1278 * processes. 1279 * 1280 * @return List of ProcessInfo objects 1281 */ getProcesses()1282 public List<ProcessInfo> getProcesses() throws DeviceNotAvailableException; 1283 1284 /** 1285 * Helper method runs the "ps" command and returns USER, PID and NAME of the given process name. 1286 * 1287 * @return ProcessInfo of given processName 1288 */ getProcessByName(String processName)1289 public ProcessInfo getProcessByName(String processName) throws DeviceNotAvailableException; 1290 1291 /** Returns the pid of the service or null if something went wrong. */ getProcessPid(String process)1292 public String getProcessPid(String process) throws DeviceNotAvailableException; 1293 1294 /** 1295 * Log a message in the logcat of the device. This is a safe call that will not throw even if 1296 * the logging fails. 1297 * 1298 * @param tag The tag under which we log our message in the logcat. 1299 * @param level The debug level of the message in the logcat. 1300 * @param format The message format. 1301 * @param args the args to be replaced via String.format(). 1302 */ logOnDevice(String tag, LogLevel level, String format, Object... args)1303 public void logOnDevice(String tag, LogLevel level, String format, Object... args); 1304 1305 /** Returns total physical memory size in bytes or -1 in case of internal error */ getTotalMemory()1306 public long getTotalMemory(); 1307 1308 /** Returns the current battery level of a device or Null if battery level unavailable. */ getBattery()1309 public Integer getBattery(); 1310 1311 /** 1312 * Returns the last time Tradefed APIs triggered a reboot in milliseconds since EPOCH as 1313 * returned by {@link System#currentTimeMillis()}. 1314 */ getLastExpectedRebootTimeMillis()1315 public long getLastExpectedRebootTimeMillis(); 1316 1317 /** 1318 * Fetch and return the list of tombstones from the devices. Requires root. 1319 * 1320 * <p>method is best-effort so if one tombstone fails to be pulled for any reason it will be 1321 * missing from the list. Only a {@link DeviceNotAvailableException} will terminate the method 1322 * early. 1323 * 1324 * @return A list of tombstone files, empty if no tombstone. 1325 * @see <a href="https://source.android.com/devices/tech/debug">Tombstones documentation</a> 1326 */ getTombstones()1327 public List<File> getTombstones() throws DeviceNotAvailableException; 1328 } 1329