core/java/android/os/Environment.java

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