Environment.java revision 4eb7cea562cd117e598a327ab4d93142589c1ae6
1/* 2 * Copyright (C) 2007 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 17package android.os; 18 19import android.app.admin.DevicePolicyManager; 20import android.content.Context; 21import android.os.storage.StorageManager; 22import android.os.storage.StorageVolume; 23import android.text.TextUtils; 24import android.util.Log; 25 26import java.io.File; 27 28/** 29 * Provides access to environment variables. 30 */ 31public class Environment { 32 private static final String TAG = "Environment"; 33 34 private static final String ENV_EXTERNAL_STORAGE = "EXTERNAL_STORAGE"; 35 private static final String ENV_ANDROID_ROOT = "ANDROID_ROOT"; 36 private static final String ENV_ANDROID_DATA = "ANDROID_DATA"; 37 private static final String ENV_ANDROID_EXPAND = "ANDROID_EXPAND"; 38 private static final String ENV_ANDROID_STORAGE = "ANDROID_STORAGE"; 39 private static final String ENV_DOWNLOAD_CACHE = "DOWNLOAD_CACHE"; 40 private static final String ENV_OEM_ROOT = "OEM_ROOT"; 41 private static final String ENV_ODM_ROOT = "ODM_ROOT"; 42 private static final String ENV_VENDOR_ROOT = "VENDOR_ROOT"; 43 44 /** {@hide} */ 45 public static final String DIR_ANDROID = "Android"; 46 private static final String DIR_DATA = "data"; 47 private static final String DIR_MEDIA = "media"; 48 private static final String DIR_OBB = "obb"; 49 private static final String DIR_FILES = "files"; 50 private static final String DIR_CACHE = "cache"; 51 52 /** {@hide} */ 53 @Deprecated 54 public static final String DIRECTORY_ANDROID = DIR_ANDROID; 55 56 private static final File DIR_ANDROID_ROOT = getDirectory(ENV_ANDROID_ROOT, "/system"); 57 private static final File DIR_ANDROID_DATA = getDirectory(ENV_ANDROID_DATA, "/data"); 58 private static final File DIR_ANDROID_EXPAND = getDirectory(ENV_ANDROID_EXPAND, "/mnt/expand"); 59 private static final File DIR_ANDROID_STORAGE = getDirectory(ENV_ANDROID_STORAGE, "/storage"); 60 private static final File DIR_DOWNLOAD_CACHE = getDirectory(ENV_DOWNLOAD_CACHE, "/cache"); 61 private static final File DIR_OEM_ROOT = getDirectory(ENV_OEM_ROOT, "/oem"); 62 private static final File DIR_ODM_ROOT = getDirectory(ENV_ODM_ROOT, "/odm"); 63 private static final File DIR_VENDOR_ROOT = getDirectory(ENV_VENDOR_ROOT, "/vendor"); 64 65 private static UserEnvironment sCurrentUser; 66 private static boolean sUserRequired; 67 68 static { 69 initForCurrentUser(); 70 } 71 72 /** {@hide} */ 73 public static void initForCurrentUser() { 74 final int userId = UserHandle.myUserId(); 75 sCurrentUser = new UserEnvironment(userId); 76 } 77 78 /** {@hide} */ 79 public static class UserEnvironment { 80 private final int mUserId; 81 82 public UserEnvironment(int userId) { 83 mUserId = userId; 84 } 85 86 public File[] getExternalDirs() { 87 final StorageVolume[] volumes = StorageManager.getVolumeList(mUserId, 88 StorageManager.FLAG_FOR_WRITE); 89 final File[] files = new File[volumes.length]; 90 for (int i = 0; i < volumes.length; i++) { 91 files[i] = volumes[i].getPathFile(); 92 } 93 return files; 94 } 95 96 @Deprecated 97 public File getExternalStorageDirectory() { 98 return getExternalDirs()[0]; 99 } 100 101 @Deprecated 102 public File getExternalStoragePublicDirectory(String type) { 103 return buildExternalStoragePublicDirs(type)[0]; 104 } 105 106 public File[] buildExternalStoragePublicDirs(String type) { 107 return buildPaths(getExternalDirs(), type); 108 } 109 110 public File[] buildExternalStorageAndroidDataDirs() { 111 return buildPaths(getExternalDirs(), DIR_ANDROID, DIR_DATA); 112 } 113 114 public File[] buildExternalStorageAndroidObbDirs() { 115 return buildPaths(getExternalDirs(), DIR_ANDROID, DIR_OBB); 116 } 117 118 public File[] buildExternalStorageAppDataDirs(String packageName) { 119 return buildPaths(getExternalDirs(), DIR_ANDROID, DIR_DATA, packageName); 120 } 121 122 public File[] buildExternalStorageAppMediaDirs(String packageName) { 123 return buildPaths(getExternalDirs(), DIR_ANDROID, DIR_MEDIA, packageName); 124 } 125 126 public File[] buildExternalStorageAppObbDirs(String packageName) { 127 return buildPaths(getExternalDirs(), DIR_ANDROID, DIR_OBB, packageName); 128 } 129 130 public File[] buildExternalStorageAppFilesDirs(String packageName) { 131 return buildPaths(getExternalDirs(), DIR_ANDROID, DIR_DATA, packageName, DIR_FILES); 132 } 133 134 public File[] buildExternalStorageAppCacheDirs(String packageName) { 135 return buildPaths(getExternalDirs(), DIR_ANDROID, DIR_DATA, packageName, DIR_CACHE); 136 } 137 } 138 139 /** 140 * Return root of the "system" partition holding the core Android OS. 141 * Always present and mounted read-only. 142 */ 143 public static File getRootDirectory() { 144 return DIR_ANDROID_ROOT; 145 } 146 147 /** {@hide} */ 148 public static File getStorageDirectory() { 149 return DIR_ANDROID_STORAGE; 150 } 151 152 /** 153 * Return root directory of the "oem" partition holding OEM customizations, 154 * if any. If present, the partition is mounted read-only. 155 * 156 * @hide 157 */ 158 public static File getOemDirectory() { 159 return DIR_OEM_ROOT; 160 } 161 162 /** 163 * Return root directory of the "odm" partition holding ODM customizations, 164 * if any. If present, the partition is mounted read-only. 165 * 166 * @hide 167 */ 168 public static File getOdmDirectory() { 169 return DIR_ODM_ROOT; 170 } 171 172 /** 173 * Return root directory of the "vendor" partition that holds vendor-provided 174 * software that should persist across simple reflashing of the "system" partition. 175 * @hide 176 */ 177 public static File getVendorDirectory() { 178 return DIR_VENDOR_ROOT; 179 } 180 181 /** 182 * Return the system directory for a user. This is for use by system 183 * services to store files relating to the user. This directory will be 184 * automatically deleted when the user is removed. 185 * 186 * @deprecated This directory is valid and still exists, but callers should 187 * <em>strongly</em> consider switching to 188 * {@link #getDataSystemCeDirectory(int)} which is protected 189 * with user credentials or 190 * {@link #getDataSystemDeDirectory(int)} which supports fast 191 * user wipe. 192 * @hide 193 */ 194 @Deprecated 195 public static File getUserSystemDirectory(int userId) { 196 return new File(new File(getDataSystemDirectory(), "users"), Integer.toString(userId)); 197 } 198 199 /** 200 * Returns the config directory for a user. This is for use by system 201 * services to store files relating to the user which should be readable by 202 * any app running as that user. 203 * 204 * @deprecated This directory is valid and still exists, but callers should 205 * <em>strongly</em> consider switching to 206 * {@link #getDataMiscCeDirectory(int)} which is protected with 207 * user credentials or {@link #getDataMiscDeDirectory(int)} 208 * which supports fast user wipe. 209 * @hide 210 */ 211 @Deprecated 212 public static File getUserConfigDirectory(int userId) { 213 return new File(new File(new File( 214 getDataDirectory(), "misc"), "user"), Integer.toString(userId)); 215 } 216 217 /** 218 * Return the user data directory. 219 */ 220 public static File getDataDirectory() { 221 return DIR_ANDROID_DATA; 222 } 223 224 /** {@hide} */ 225 public static File getDataDirectory(String volumeUuid) { 226 if (TextUtils.isEmpty(volumeUuid)) { 227 return DIR_ANDROID_DATA; 228 } else { 229 return new File("/mnt/expand/" + volumeUuid); 230 } 231 } 232 233 /** {@hide} */ 234 public static File getExpandDirectory() { 235 return DIR_ANDROID_EXPAND; 236 } 237 238 /** {@hide} */ 239 public static File getDataSystemDirectory() { 240 return new File(getDataDirectory(), "system"); 241 } 242 243 /** 244 * Returns the base directory for per-user system directory, device encrypted. 245 * {@hide} 246 */ 247 public static File getDataSystemDeDirectory() { 248 return buildPath(getDataDirectory(), "system_de"); 249 } 250 251 /** 252 * Returns the base directory for per-user system directory, credential encrypted. 253 * {@hide} 254 */ 255 public static File getDataSystemCeDirectory() { 256 return buildPath(getDataDirectory(), "system_ce"); 257 } 258 259 /** {@hide} */ 260 public static File getDataSystemCeDirectory(int userId) { 261 return buildPath(getDataDirectory(), "system_ce", String.valueOf(userId)); 262 } 263 264 /** {@hide} */ 265 public static File getDataSystemDeDirectory(int userId) { 266 return buildPath(getDataDirectory(), "system_de", String.valueOf(userId)); 267 } 268 269 /** {@hide} */ 270 public static File getDataMiscDirectory() { 271 return new File(getDataDirectory(), "misc"); 272 } 273 274 /** {@hide} */ 275 public static File getDataMiscCeDirectory() { 276 return buildPath(getDataDirectory(), "misc_ce"); 277 } 278 279 /** {@hide} */ 280 public static File getDataMiscCeDirectory(int userId) { 281 return buildPath(getDataDirectory(), "misc_ce", String.valueOf(userId)); 282 } 283 284 /** {@hide} */ 285 public static File getDataMiscDeDirectory(int userId) { 286 return buildPath(getDataDirectory(), "misc_de", String.valueOf(userId)); 287 } 288 289 private static File getDataProfilesDeDirectory(int userId) { 290 return buildPath(getDataDirectory(), "misc", "profiles", "cur", String.valueOf(userId)); 291 } 292 293 /** {@hide} */ 294 public static File getReferenceProfile(String packageName) { 295 return buildPath(getDataDirectory(), "misc", "profiles", "ref", packageName); 296 } 297 298 /** {@hide} */ 299 public static File getDataProfilesDePackageDirectory(int userId, String packageName) { 300 return buildPath(getDataProfilesDeDirectory(userId), packageName); 301 } 302 303 /** {@hide} */ 304 public static File getDataProfilesDeForeignDexDirectory(int userId) { 305 return buildPath(getDataProfilesDeDirectory(userId), "foreign-dex"); 306 } 307 308 /** {@hide} */ 309 public static File getDataAppDirectory(String volumeUuid) { 310 return new File(getDataDirectory(volumeUuid), "app"); 311 } 312 313 /** {@hide} */ 314 public static File getDataUserCeDirectory(String volumeUuid) { 315 return new File(getDataDirectory(volumeUuid), "user"); 316 } 317 318 /** {@hide} */ 319 public static File getDataUserCeDirectory(String volumeUuid, int userId) { 320 return new File(getDataUserCeDirectory(volumeUuid), String.valueOf(userId)); 321 } 322 323 /** {@hide} */ 324 public static File getDataUserCePackageDirectory(String volumeUuid, int userId, 325 String packageName) { 326 // TODO: keep consistent with installd 327 return new File(getDataUserCeDirectory(volumeUuid, userId), packageName); 328 } 329 330 /** {@hide} */ 331 public static File getDataUserDeDirectory(String volumeUuid) { 332 return new File(getDataDirectory(volumeUuid), "user_de"); 333 } 334 335 /** {@hide} */ 336 public static File getDataUserDeDirectory(String volumeUuid, int userId) { 337 return new File(getDataUserDeDirectory(volumeUuid), String.valueOf(userId)); 338 } 339 340 /** {@hide} */ 341 public static File getDataUserDePackageDirectory(String volumeUuid, int userId, 342 String packageName) { 343 // TODO: keep consistent with installd 344 return new File(getDataUserDeDirectory(volumeUuid, userId), packageName); 345 } 346 347 /** 348 * Return preloads directory. 349 * <p>This directory may contain pre-loaded content such as 350 * {@link #getDataPreloadsDemoDirectory() demo videos} and 351 * {@link #getDataPreloadsAppsDirectory() APK files} . 352 * {@hide} 353 */ 354 public static File getDataPreloadsDirectory() { 355 return new File(getDataDirectory(), "preloads"); 356 } 357 358 /** 359 * @see #getDataPreloadsDirectory() 360 * {@hide} 361 */ 362 public static File getDataPreloadsDemoDirectory() { 363 return new File(getDataPreloadsDirectory(), "demo"); 364 } 365 366 /** 367 * @see #getDataPreloadsDirectory() 368 * {@hide} 369 */ 370 public static File getDataPreloadsAppsDirectory() { 371 return new File(getDataPreloadsDirectory(), "apps"); 372 } 373 374 /** 375 * @see #getDataPreloadsDirectory() 376 * {@hide} 377 */ 378 public static File getDataPreloadsMediaDirectory() { 379 return new File(getDataPreloadsDirectory(), "media"); 380 } 381 382 /** 383 * Returns location of preloaded cache directory for package name 384 * @see #getDataPreloadsDirectory() 385 * {@hide} 386 */ 387 public static File getDataPreloadsFileCacheDirectory(String packageName) { 388 return new File(getDataPreloadsFileCacheDirectory(), packageName); 389 } 390 391 /** 392 * Returns location of preloaded cache directory. 393 * @see #getDataPreloadsDirectory() 394 * {@hide} 395 */ 396 public static File getDataPreloadsFileCacheDirectory() { 397 return new File(getDataPreloadsDirectory(), "file_cache"); 398 } 399 400 /** 401 * Return the primary shared/external storage directory. This directory may 402 * not currently be accessible if it has been mounted by the user on their 403 * computer, has been removed from the device, or some other problem has 404 * happened. You can determine its current state with 405 * {@link #getExternalStorageState()}. 406 * <p> 407 * <em>Note: don't be confused by the word "external" here. This directory 408 * can better be thought as media/shared storage. It is a filesystem that 409 * can hold a relatively large amount of data and that is shared across all 410 * applications (does not enforce permissions). Traditionally this is an SD 411 * card, but it may also be implemented as built-in storage in a device that 412 * is distinct from the protected internal storage and can be mounted as a 413 * filesystem on a computer.</em> 414 * <p> 415 * On devices with multiple users (as described by {@link UserManager}), 416 * each user has their own isolated shared storage. Applications only have 417 * access to the shared storage for the user they're running as. 418 * <p> 419 * In devices with multiple shared/external storage directories, this 420 * directory represents the primary storage that the user will interact 421 * with. Access to secondary storage is available through 422 * {@link Context#getExternalFilesDirs(String)}, 423 * {@link Context#getExternalCacheDirs()}, and 424 * {@link Context#getExternalMediaDirs()}. 425 * <p> 426 * Applications should not directly use this top-level directory, in order 427 * to avoid polluting the user's root namespace. Any files that are private 428 * to the application should be placed in a directory returned by 429 * {@link android.content.Context#getExternalFilesDir 430 * Context.getExternalFilesDir}, which the system will take care of deleting 431 * if the application is uninstalled. Other shared files should be placed in 432 * one of the directories returned by 433 * {@link #getExternalStoragePublicDirectory}. 434 * <p> 435 * Writing to this path requires the 436 * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} permission, 437 * and starting in {@link android.os.Build.VERSION_CODES#KITKAT}, read access requires the 438 * {@link android.Manifest.permission#READ_EXTERNAL_STORAGE} permission, 439 * which is automatically granted if you hold the write permission. 440 * <p> 441 * Starting in {@link android.os.Build.VERSION_CODES#KITKAT}, if your 442 * application only needs to store internal data, consider using 443 * {@link Context#getExternalFilesDir(String)}, 444 * {@link Context#getExternalCacheDir()}, or 445 * {@link Context#getExternalMediaDirs()}, which require no permissions to 446 * read or write. 447 * <p> 448 * This path may change between platform versions, so applications should 449 * only persist relative paths. 450 * <p> 451 * Here is an example of typical code to monitor the state of external 452 * storage: 453 * <p> 454 * {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java 455 * monitor_storage} 456 * 457 * @see #getExternalStorageState() 458 * @see #isExternalStorageRemovable() 459 */ 460 public static File getExternalStorageDirectory() { 461 throwIfUserRequired(); 462 return sCurrentUser.getExternalDirs()[0]; 463 } 464 465 /** {@hide} */ 466 public static File getLegacyExternalStorageDirectory() { 467 return new File(System.getenv(ENV_EXTERNAL_STORAGE)); 468 } 469 470 /** {@hide} */ 471 public static File getLegacyExternalStorageObbDirectory() { 472 return buildPath(getLegacyExternalStorageDirectory(), DIR_ANDROID, DIR_OBB); 473 } 474 475 /** 476 * Standard directory in which to place any audio files that should be 477 * in the regular list of music for the user. 478 * This may be combined with 479 * {@link #DIRECTORY_PODCASTS}, {@link #DIRECTORY_NOTIFICATIONS}, 480 * {@link #DIRECTORY_ALARMS}, and {@link #DIRECTORY_RINGTONES} as a series 481 * of directories to categories a particular audio file as more than one 482 * type. 483 */ 484 public static String DIRECTORY_MUSIC = "Music"; 485 486 /** 487 * Standard directory in which to place any audio files that should be 488 * in the list of podcasts that the user can select (not as regular 489 * music). 490 * This may be combined with {@link #DIRECTORY_MUSIC}, 491 * {@link #DIRECTORY_NOTIFICATIONS}, 492 * {@link #DIRECTORY_ALARMS}, and {@link #DIRECTORY_RINGTONES} as a series 493 * of directories to categories a particular audio file as more than one 494 * type. 495 */ 496 public static String DIRECTORY_PODCASTS = "Podcasts"; 497 498 /** 499 * Standard directory in which to place any audio files that should be 500 * in the list of ringtones that the user can select (not as regular 501 * music). 502 * This may be combined with {@link #DIRECTORY_MUSIC}, 503 * {@link #DIRECTORY_PODCASTS}, {@link #DIRECTORY_NOTIFICATIONS}, and 504 * {@link #DIRECTORY_ALARMS} as a series 505 * of directories to categories a particular audio file as more than one 506 * type. 507 */ 508 public static String DIRECTORY_RINGTONES = "Ringtones"; 509 510 /** 511 * Standard directory in which to place any audio files that should be 512 * in the list of alarms that the user can select (not as regular 513 * music). 514 * This may be combined with {@link #DIRECTORY_MUSIC}, 515 * {@link #DIRECTORY_PODCASTS}, {@link #DIRECTORY_NOTIFICATIONS}, 516 * and {@link #DIRECTORY_RINGTONES} as a series 517 * of directories to categories a particular audio file as more than one 518 * type. 519 */ 520 public static String DIRECTORY_ALARMS = "Alarms"; 521 522 /** 523 * Standard directory in which to place any audio files that should be 524 * in the list of notifications that the user can select (not as regular 525 * music). 526 * This may be combined with {@link #DIRECTORY_MUSIC}, 527 * {@link #DIRECTORY_PODCASTS}, 528 * {@link #DIRECTORY_ALARMS}, and {@link #DIRECTORY_RINGTONES} as a series 529 * of directories to categories a particular audio file as more than one 530 * type. 531 */ 532 public static String DIRECTORY_NOTIFICATIONS = "Notifications"; 533 534 /** 535 * Standard directory in which to place pictures that are available to 536 * the user. Note that this is primarily a convention for the top-level 537 * public directory, as the media scanner will find and collect pictures 538 * in any directory. 539 */ 540 public static String DIRECTORY_PICTURES = "Pictures"; 541 542 /** 543 * Standard directory in which to place movies that are available to 544 * the user. Note that this is primarily a convention for the top-level 545 * public directory, as the media scanner will find and collect movies 546 * in any directory. 547 */ 548 public static String DIRECTORY_MOVIES = "Movies"; 549 550 /** 551 * Standard directory in which to place files that have been downloaded by 552 * the user. Note that this is primarily a convention for the top-level 553 * public directory, you are free to download files anywhere in your own 554 * private directories. Also note that though the constant here is 555 * named DIRECTORY_DOWNLOADS (plural), the actual file name is non-plural for 556 * backwards compatibility reasons. 557 */ 558 public static String DIRECTORY_DOWNLOADS = "Download"; 559 560 /** 561 * The traditional location for pictures and videos when mounting the 562 * device as a camera. Note that this is primarily a convention for the 563 * top-level public directory, as this convention makes no sense elsewhere. 564 */ 565 public static String DIRECTORY_DCIM = "DCIM"; 566 567 /** 568 * Standard directory in which to place documents that have been created by 569 * the user. 570 */ 571 public static String DIRECTORY_DOCUMENTS = "Documents"; 572 573 /** 574 * List of standard storage directories. 575 * <p> 576 * Each of its values have its own constant: 577 * <ul> 578 * <li>{@link #DIRECTORY_MUSIC} 579 * <li>{@link #DIRECTORY_PODCASTS} 580 * <li>{@link #DIRECTORY_ALARMS} 581 * <li>{@link #DIRECTORY_RINGTONES} 582 * <li>{@link #DIRECTORY_NOTIFICATIONS} 583 * <li>{@link #DIRECTORY_PICTURES} 584 * <li>{@link #DIRECTORY_MOVIES} 585 * <li>{@link #DIRECTORY_DOWNLOADS} 586 * <li>{@link #DIRECTORY_DCIM} 587 * <li>{@link #DIRECTORY_DOCUMENTS} 588 * </ul> 589 * @hide 590 */ 591 public static final String[] STANDARD_DIRECTORIES = { 592 DIRECTORY_MUSIC, 593 DIRECTORY_PODCASTS, 594 DIRECTORY_RINGTONES, 595 DIRECTORY_ALARMS, 596 DIRECTORY_NOTIFICATIONS, 597 DIRECTORY_PICTURES, 598 DIRECTORY_MOVIES, 599 DIRECTORY_DOWNLOADS, 600 DIRECTORY_DCIM, 601 DIRECTORY_DOCUMENTS 602 }; 603 604 /** 605 * @hide 606 */ 607 public static boolean isStandardDirectory(String dir) { 608 for (String valid : STANDARD_DIRECTORIES) { 609 if (valid.equals(dir)) { 610 return true; 611 } 612 } 613 return false; 614 } 615 616 /** 617 * Get a top-level shared/external storage directory for placing files of a 618 * particular type. This is where the user will typically place and manage 619 * their own files, so you should be careful about what you put here to 620 * ensure you don't erase their files or get in the way of their own 621 * organization. 622 * <p> 623 * On devices with multiple users (as described by {@link UserManager}), 624 * each user has their own isolated shared storage. Applications only have 625 * access to the shared storage for the user they're running as. 626 * </p> 627 * <p> 628 * Here is an example of typical code to manipulate a picture on the public 629 * shared storage: 630 * </p> 631 * {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java 632 * public_picture} 633 * 634 * @param type The type of storage directory to return. Should be one of 635 * {@link #DIRECTORY_MUSIC}, {@link #DIRECTORY_PODCASTS}, 636 * {@link #DIRECTORY_RINGTONES}, {@link #DIRECTORY_ALARMS}, 637 * {@link #DIRECTORY_NOTIFICATIONS}, {@link #DIRECTORY_PICTURES}, 638 * {@link #DIRECTORY_MOVIES}, {@link #DIRECTORY_DOWNLOADS}, 639 * {@link #DIRECTORY_DCIM}, or {@link #DIRECTORY_DOCUMENTS}. May not be null. 640 * @return Returns the File path for the directory. Note that this directory 641 * may not yet exist, so you must make sure it exists before using 642 * it such as with {@link File#mkdirs File.mkdirs()}. 643 */ 644 public static File getExternalStoragePublicDirectory(String type) { 645 throwIfUserRequired(); 646 return sCurrentUser.buildExternalStoragePublicDirs(type)[0]; 647 } 648 649 /** 650 * Returns the path for android-specific data on the SD card. 651 * @hide 652 */ 653 public static File[] buildExternalStorageAndroidDataDirs() { 654 throwIfUserRequired(); 655 return sCurrentUser.buildExternalStorageAndroidDataDirs(); 656 } 657 658 /** 659 * Generates the raw path to an application's data 660 * @hide 661 */ 662 public static File[] buildExternalStorageAppDataDirs(String packageName) { 663 throwIfUserRequired(); 664 return sCurrentUser.buildExternalStorageAppDataDirs(packageName); 665 } 666 667 /** 668 * Generates the raw path to an application's media 669 * @hide 670 */ 671 public static File[] buildExternalStorageAppMediaDirs(String packageName) { 672 throwIfUserRequired(); 673 return sCurrentUser.buildExternalStorageAppMediaDirs(packageName); 674 } 675 676 /** 677 * Generates the raw path to an application's OBB files 678 * @hide 679 */ 680 public static File[] buildExternalStorageAppObbDirs(String packageName) { 681 throwIfUserRequired(); 682 return sCurrentUser.buildExternalStorageAppObbDirs(packageName); 683 } 684 685 /** 686 * Generates the path to an application's files. 687 * @hide 688 */ 689 public static File[] buildExternalStorageAppFilesDirs(String packageName) { 690 throwIfUserRequired(); 691 return sCurrentUser.buildExternalStorageAppFilesDirs(packageName); 692 } 693 694 /** 695 * Generates the path to an application's cache. 696 * @hide 697 */ 698 public static File[] buildExternalStorageAppCacheDirs(String packageName) { 699 throwIfUserRequired(); 700 return sCurrentUser.buildExternalStorageAppCacheDirs(packageName); 701 } 702 703 /** 704 * Return the download/cache content directory. 705 */ 706 public static File getDownloadCacheDirectory() { 707 return DIR_DOWNLOAD_CACHE; 708 } 709 710 /** 711 * Unknown storage state, such as when a path isn't backed by known storage 712 * media. 713 * 714 * @see #getExternalStorageState(File) 715 */ 716 public static final String MEDIA_UNKNOWN = "unknown"; 717 718 /** 719 * Storage state if the media is not present. 720 * 721 * @see #getExternalStorageState(File) 722 */ 723 public static final String MEDIA_REMOVED = "removed"; 724 725 /** 726 * Storage state if the media is present but not mounted. 727 * 728 * @see #getExternalStorageState(File) 729 */ 730 public static final String MEDIA_UNMOUNTED = "unmounted"; 731 732 /** 733 * Storage state if the media is present and being disk-checked. 734 * 735 * @see #getExternalStorageState(File) 736 */ 737 public static final String MEDIA_CHECKING = "checking"; 738 739 /** 740 * Storage state if the media is present but is blank or is using an 741 * unsupported filesystem. 742 * 743 * @see #getExternalStorageState(File) 744 */ 745 public static final String MEDIA_NOFS = "nofs"; 746 747 /** 748 * Storage state if the media is present and mounted at its mount point with 749 * read/write access. 750 * 751 * @see #getExternalStorageState(File) 752 */ 753 public static final String MEDIA_MOUNTED = "mounted"; 754 755 /** 756 * Storage state if the media is present and mounted at its mount point with 757 * read-only access. 758 * 759 * @see #getExternalStorageState(File) 760 */ 761 public static final String MEDIA_MOUNTED_READ_ONLY = "mounted_ro"; 762 763 /** 764 * Storage state if the media is present not mounted, and shared via USB 765 * mass storage. 766 * 767 * @see #getExternalStorageState(File) 768 */ 769 public static final String MEDIA_SHARED = "shared"; 770 771 /** 772 * Storage state if the media was removed before it was unmounted. 773 * 774 * @see #getExternalStorageState(File) 775 */ 776 public static final String MEDIA_BAD_REMOVAL = "bad_removal"; 777 778 /** 779 * Storage state if the media is present but cannot be mounted. Typically 780 * this happens if the file system on the media is corrupted. 781 * 782 * @see #getExternalStorageState(File) 783 */ 784 public static final String MEDIA_UNMOUNTABLE = "unmountable"; 785 786 /** 787 * Storage state if the media is in the process of being ejected. 788 * 789 * @see #getExternalStorageState(File) 790 */ 791 public static final String MEDIA_EJECTING = "ejecting"; 792 793 /** 794 * Returns the current state of the primary shared/external storage media. 795 * 796 * @see #getExternalStorageDirectory() 797 * @return one of {@link #MEDIA_UNKNOWN}, {@link #MEDIA_REMOVED}, 798 * {@link #MEDIA_UNMOUNTED}, {@link #MEDIA_CHECKING}, 799 * {@link #MEDIA_NOFS}, {@link #MEDIA_MOUNTED}, 800 * {@link #MEDIA_MOUNTED_READ_ONLY}, {@link #MEDIA_SHARED}, 801 * {@link #MEDIA_BAD_REMOVAL}, or {@link #MEDIA_UNMOUNTABLE}. 802 */ 803 public static String getExternalStorageState() { 804 final File externalDir = sCurrentUser.getExternalDirs()[0]; 805 return getExternalStorageState(externalDir); 806 } 807 808 /** 809 * @deprecated use {@link #getExternalStorageState(File)} 810 */ 811 @Deprecated 812 public static String getStorageState(File path) { 813 return getExternalStorageState(path); 814 } 815 816 /** 817 * Returns the current state of the shared/external storage media at the 818 * given path. 819 * 820 * @return one of {@link #MEDIA_UNKNOWN}, {@link #MEDIA_REMOVED}, 821 * {@link #MEDIA_UNMOUNTED}, {@link #MEDIA_CHECKING}, 822 * {@link #MEDIA_NOFS}, {@link #MEDIA_MOUNTED}, 823 * {@link #MEDIA_MOUNTED_READ_ONLY}, {@link #MEDIA_SHARED}, 824 * {@link #MEDIA_BAD_REMOVAL}, or {@link #MEDIA_UNMOUNTABLE}. 825 */ 826 public static String getExternalStorageState(File path) { 827 final StorageVolume volume = StorageManager.getStorageVolume(path, UserHandle.myUserId()); 828 if (volume != null) { 829 return volume.getState(); 830 } else { 831 return MEDIA_UNKNOWN; 832 } 833 } 834 835 /** 836 * Returns whether the primary shared/external storage media is physically 837 * removable. 838 * 839 * @return true if the storage device can be removed (such as an SD card), 840 * or false if the storage device is built in and cannot be 841 * physically removed. 842 */ 843 public static boolean isExternalStorageRemovable() { 844 if (isStorageDisabled()) return false; 845 final File externalDir = sCurrentUser.getExternalDirs()[0]; 846 return isExternalStorageRemovable(externalDir); 847 } 848 849 /** 850 * Returns whether the shared/external storage media at the given path is 851 * physically removable. 852 * 853 * @return true if the storage device can be removed (such as an SD card), 854 * or false if the storage device is built in and cannot be 855 * physically removed. 856 * @throws IllegalArgumentException if the path is not a valid storage 857 * device. 858 */ 859 public static boolean isExternalStorageRemovable(File path) { 860 final StorageVolume volume = StorageManager.getStorageVolume(path, UserHandle.myUserId()); 861 if (volume != null) { 862 return volume.isRemovable(); 863 } else { 864 throw new IllegalArgumentException("Failed to find storage device at " + path); 865 } 866 } 867 868 /** 869 * Returns whether the primary shared/external storage media is emulated. 870 * <p> 871 * The contents of emulated storage devices are backed by a private user 872 * data partition, which means there is little benefit to apps storing data 873 * here instead of the private directories returned by 874 * {@link Context#getFilesDir()}, etc. 875 * <p> 876 * This returns true when emulated storage is backed by either internal 877 * storage or an adopted storage device. 878 * 879 * @see DevicePolicyManager#setStorageEncryption(android.content.ComponentName, 880 * boolean) 881 */ 882 public static boolean isExternalStorageEmulated() { 883 if (isStorageDisabled()) return false; 884 final File externalDir = sCurrentUser.getExternalDirs()[0]; 885 return isExternalStorageEmulated(externalDir); 886 } 887 888 /** 889 * Returns whether the shared/external storage media at the given path is 890 * emulated. 891 * <p> 892 * The contents of emulated storage devices are backed by a private user 893 * data partition, which means there is little benefit to apps storing data 894 * here instead of the private directories returned by 895 * {@link Context#getFilesDir()}, etc. 896 * <p> 897 * This returns true when emulated storage is backed by either internal 898 * storage or an adopted storage device. 899 * 900 * @throws IllegalArgumentException if the path is not a valid storage 901 * device. 902 */ 903 public static boolean isExternalStorageEmulated(File path) { 904 final StorageVolume volume = StorageManager.getStorageVolume(path, UserHandle.myUserId()); 905 if (volume != null) { 906 return volume.isEmulated(); 907 } else { 908 throw new IllegalArgumentException("Failed to find storage device at " + path); 909 } 910 } 911 912 static File getDirectory(String variableName, String defaultPath) { 913 String path = System.getenv(variableName); 914 return path == null ? new File(defaultPath) : new File(path); 915 } 916 917 /** {@hide} */ 918 public static void setUserRequired(boolean userRequired) { 919 sUserRequired = userRequired; 920 } 921 922 private static void throwIfUserRequired() { 923 if (sUserRequired) { 924 Log.wtf(TAG, "Path requests must specify a user by using UserEnvironment", 925 new Throwable()); 926 } 927 } 928 929 /** 930 * Append path segments to each given base path, returning result. 931 * 932 * @hide 933 */ 934 public static File[] buildPaths(File[] base, String... segments) { 935 File[] result = new File[base.length]; 936 for (int i = 0; i < base.length; i++) { 937 result[i] = buildPath(base[i], segments); 938 } 939 return result; 940 } 941 942 /** 943 * Append path segments to given base path, returning result. 944 * 945 * @hide 946 */ 947 public static File buildPath(File base, String... segments) { 948 File cur = base; 949 for (String segment : segments) { 950 if (cur == null) { 951 cur = new File(segment); 952 } else { 953 cur = new File(cur, segment); 954 } 955 } 956 return cur; 957 } 958 959 private static boolean isStorageDisabled() { 960 return SystemProperties.getBoolean("config.disable_storage", false); 961 } 962 963 /** 964 * If the given path exists on emulated external storage, return the 965 * translated backing path hosted on internal storage. This bypasses any 966 * emulation later, improving performance. This is <em>only</em> suitable 967 * for read-only access. 968 * <p> 969 * Returns original path if given path doesn't meet these criteria. Callers 970 * must hold {@link android.Manifest.permission#WRITE_MEDIA_STORAGE} 971 * permission. 972 * 973 * @hide 974 */ 975 public static File maybeTranslateEmulatedPathToInternal(File path) { 976 return StorageManager.maybeTranslateEmulatedPathToInternal(path); 977 } 978} 979