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.app.admin.DevicePolicyManager;
  20 import android.content.Context;
  21 import android.os.storage.StorageManager;
  22 import android.os.storage.StorageVolume;
  23 import android.text.TextUtils;
  24 import android.util.Log;
  25
  26 import java.io.File;
  27
  28 /**
  29  * Provides access to environment variables.
  30  */
  31 public 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(int userId) {
 276         return buildPath(getDataDirectory(), "misc_ce", String.valueOf(userId));
 277     }
 278
 279     /** {@hide} */
 280     public static File getDataMiscDeDirectory(int userId) {
 281         return buildPath(getDataDirectory(), "misc_de", String.valueOf(userId));
 282     }
 283
 284     private static File getDataProfilesDeDirectory(int userId) {
 285         return buildPath(getDataDirectory(), "misc", "profiles", "cur", String.valueOf(userId));
 286     }
 287
 288     /** {@hide} */
 289     public static File getReferenceProfile(String packageName) {
 290         return buildPath(getDataDirectory(), "misc", "profiles", "ref", packageName);
 291     }
 292
 293     /** {@hide} */
 294     public static File getDataProfilesDePackageDirectory(int userId, String packageName) {
 295         return buildPath(getDataProfilesDeDirectory(userId), packageName);
 296     }
 297
 298     /** {@hide} */
 299     public static File getDataProfilesDeForeignDexDirectory(int userId) {
 300         return buildPath(getDataProfilesDeDirectory(userId), "foreign-dex");
 301     }
 302
 303     /** {@hide} */
 304     public static File getDataAppDirectory(String volumeUuid) {
 305         return new File(getDataDirectory(volumeUuid), "app");
 306     }
 307
 308     /** {@hide} */
 309     public static File getDataAppEphemeralDirectory(String volumeUuid) {
 310         return new File(getDataDirectory(volumeUuid), "app-ephemeral");
 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      * Return the primary shared/external storage directory. This directory may
 384      * not currently be accessible if it has been mounted by the user on their
 385      * computer, has been removed from the device, or some other problem has
 386      * happened. You can determine its current state with
 387      * {@link #getExternalStorageState()}.
 388      * <p>
 389      * <em>Note: don't be confused by the word "external" here. This directory
 390      * can better be thought as media/shared storage. It is a filesystem that
 391      * can hold a relatively large amount of data and that is shared across all
 392      * applications (does not enforce permissions). Traditionally this is an SD
 393      * card, but it may also be implemented as built-in storage in a device that
 394      * is distinct from the protected internal storage and can be mounted as a
 395      * filesystem on a computer.</em>
 396      * <p>
 397      * On devices with multiple users (as described by {@link UserManager}),
 398      * each user has their own isolated shared storage. Applications only have
 399      * access to the shared storage for the user they're running as.
 400      * <p>
 401      * In devices with multiple shared/external storage directories, this
 402      * directory represents the primary storage that the user will interact
 403      * with. Access to secondary storage is available through
 404      * {@link Context#getExternalFilesDirs(String)},
 405      * {@link Context#getExternalCacheDirs()}, and
 406      * {@link Context#getExternalMediaDirs()}.
 407      * <p>
 408      * Applications should not directly use this top-level directory, in order
 409      * to avoid polluting the user's root namespace. Any files that are private
 410      * to the application should be placed in a directory returned by
 411      * {@link android.content.Context#getExternalFilesDir
 412      * Context.getExternalFilesDir}, which the system will take care of deleting
 413      * if the application is uninstalled. Other shared files should be placed in
 414      * one of the directories returned by
 415      * {@link #getExternalStoragePublicDirectory}.
 416      * <p>
 417      * Writing to this path requires the
 418      * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} permission,
 419      * and starting in {@link android.os.Build.VERSION_CODES#KITKAT}, read access requires the
 420      * {@link android.Manifest.permission#READ_EXTERNAL_STORAGE} permission,
 421      * which is automatically granted if you hold the write permission.
 422      * <p>
 423      * Starting in {@link android.os.Build.VERSION_CODES#KITKAT}, if your
 424      * application only needs to store internal data, consider using
 425      * {@link Context#getExternalFilesDir(String)},
 426      * {@link Context#getExternalCacheDir()}, or
 427      * {@link Context#getExternalMediaDirs()}, which require no permissions to
 428      * read or write.
 429      * <p>
 430      * This path may change between platform versions, so applications should
 431      * only persist relative paths.
 432      * <p>
 433      * Here is an example of typical code to monitor the state of external
 434      * storage:
 435      * <p>
 436      * {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java
 437      * monitor_storage}
 438      *
 439      * @see #getExternalStorageState()
 440      * @see #isExternalStorageRemovable()
 441      */
 442     public static File getExternalStorageDirectory() {
 443         throwIfUserRequired();
 444         return sCurrentUser.getExternalDirs()[0];
 445     }
 446
 447     /** {@hide} */
 448     public static File getLegacyExternalStorageDirectory() {
 449         return new File(System.getenv(ENV_EXTERNAL_STORAGE));
 450     }
 451
 452     /** {@hide} */
 453     public static File getLegacyExternalStorageObbDirectory() {
 454         return buildPath(getLegacyExternalStorageDirectory(), DIR_ANDROID, DIR_OBB);
 455     }
 456
 457     /**
 458      * Standard directory in which to place any audio files that should be
 459      * in the regular list of music for the user.
 460      * This may be combined with
 461      * {@link #DIRECTORY_PODCASTS}, {@link #DIRECTORY_NOTIFICATIONS},
 462      * {@link #DIRECTORY_ALARMS}, and {@link #DIRECTORY_RINGTONES} as a series
 463      * of directories to categories a particular audio file as more than one
 464      * type.
 465      */
 466     public static String DIRECTORY_MUSIC = "Music";
 467
 468     /**
 469      * Standard directory in which to place any audio files that should be
 470      * in the list of podcasts that the user can select (not as regular
 471      * music).
 472      * This may be combined with {@link #DIRECTORY_MUSIC},
 473      * {@link #DIRECTORY_NOTIFICATIONS},
 474      * {@link #DIRECTORY_ALARMS}, and {@link #DIRECTORY_RINGTONES} as a series
 475      * of directories to categories a particular audio file as more than one
 476      * type.
 477      */
 478     public static String DIRECTORY_PODCASTS = "Podcasts";
 479
 480     /**
 481      * Standard directory in which to place any audio files that should be
 482      * in the list of ringtones that the user can select (not as regular
 483      * music).
 484      * This may be combined with {@link #DIRECTORY_MUSIC},
 485      * {@link #DIRECTORY_PODCASTS}, {@link #DIRECTORY_NOTIFICATIONS}, and
 486      * {@link #DIRECTORY_ALARMS} as a series
 487      * of directories to categories a particular audio file as more than one
 488      * type.
 489      */
 490     public static String DIRECTORY_RINGTONES = "Ringtones";
 491
 492     /**
 493      * Standard directory in which to place any audio files that should be
 494      * in the list of alarms that the user can select (not as regular
 495      * music).
 496      * This may be combined with {@link #DIRECTORY_MUSIC},
 497      * {@link #DIRECTORY_PODCASTS}, {@link #DIRECTORY_NOTIFICATIONS},
 498      * and {@link #DIRECTORY_RINGTONES} as a series
 499      * of directories to categories a particular audio file as more than one
 500      * type.
 501      */
 502     public static String DIRECTORY_ALARMS = "Alarms";
 503
 504     /**
 505      * Standard directory in which to place any audio files that should be
 506      * in the list of notifications that the user can select (not as regular
 507      * music).
 508      * This may be combined with {@link #DIRECTORY_MUSIC},
 509      * {@link #DIRECTORY_PODCASTS},
 510      * {@link #DIRECTORY_ALARMS}, and {@link #DIRECTORY_RINGTONES} as a series
 511      * of directories to categories a particular audio file as more than one
 512      * type.
 513      */
 514     public static String DIRECTORY_NOTIFICATIONS = "Notifications";
 515
 516     /**
 517      * Standard directory in which to place pictures that are available to
 518      * the user.  Note that this is primarily a convention for the top-level
 519      * public directory, as the media scanner will find and collect pictures
 520      * in any directory.
 521      */
 522     public static String DIRECTORY_PICTURES = "Pictures";
 523
 524     /**
 525      * Standard directory in which to place movies that are available to
 526      * the user.  Note that this is primarily a convention for the top-level
 527      * public directory, as the media scanner will find and collect movies
 528      * in any directory.
 529      */
 530     public static String DIRECTORY_MOVIES = "Movies";
 531
 532     /**
 533      * Standard directory in which to place files that have been downloaded by
 534      * the user.  Note that this is primarily a convention for the top-level
 535      * public directory, you are free to download files anywhere in your own
 536      * private directories.  Also note that though the constant here is
 537      * named DIRECTORY_DOWNLOADS (plural), the actual file name is non-plural for
 538      * backwards compatibility reasons.
 539      */
 540     public static String DIRECTORY_DOWNLOADS = "Download";
 541
 542     /**
 543      * The traditional location for pictures and videos when mounting the
 544      * device as a camera.  Note that this is primarily a convention for the
 545      * top-level public directory, as this convention makes no sense elsewhere.
 546      */
 547     public static String DIRECTORY_DCIM = "DCIM";
 548
 549     /**
 550      * Standard directory in which to place documents that have been created by
 551      * the user.
 552      */
 553     public static String DIRECTORY_DOCUMENTS = "Documents";
 554
 555     /**
 556      * List of standard storage directories.
 557      * <p>
 558      * Each of its values have its own constant:
 559      * <ul>
 560      *   <li>{@link #DIRECTORY_MUSIC}
 561      *   <li>{@link #DIRECTORY_PODCASTS}
 562      *   <li>{@link #DIRECTORY_ALARMS}
 563      *   <li>{@link #DIRECTORY_RINGTONES}
 564      *   <li>{@link #DIRECTORY_NOTIFICATIONS}
 565      *   <li>{@link #DIRECTORY_PICTURES}
 566      *   <li>{@link #DIRECTORY_MOVIES}
 567      *   <li>{@link #DIRECTORY_DOWNLOADS}
 568      *   <li>{@link #DIRECTORY_DCIM}
 569      *   <li>{@link #DIRECTORY_DOCUMENTS}
 570      * </ul>
 571      * @hide
 572      */
 573     public static final String[] STANDARD_DIRECTORIES = {
 574             DIRECTORY_MUSIC,
 575             DIRECTORY_PODCASTS,
 576             DIRECTORY_RINGTONES,
 577             DIRECTORY_ALARMS,
 578             DIRECTORY_NOTIFICATIONS,
 579             DIRECTORY_PICTURES,
 580             DIRECTORY_MOVIES,
 581             DIRECTORY_DOWNLOADS,
 582             DIRECTORY_DCIM,
 583             DIRECTORY_DOCUMENTS
 584     };
 585
 586     /**
 587      * @hide
 588      */
 589     public static boolean isStandardDirectory(String dir) {
 590         for (String valid : STANDARD_DIRECTORIES) {
 591             if (valid.equals(dir)) {
 592                 return true;
 593             }
 594         }
 595         return false;
 596     }
 597
 598     /**
 599      * Get a top-level shared/external storage directory for placing files of a
 600      * particular type. This is where the user will typically place and manage
 601      * their own files, so you should be careful about what you put here to
 602      * ensure you don't erase their files or get in the way of their own
 603      * organization.
 604      * <p>
 605      * On devices with multiple users (as described by {@link UserManager}),
 606      * each user has their own isolated shared storage. Applications only have
 607      * access to the shared storage for the user they're running as.
 608      * </p>
 609      * <p>
 610      * Here is an example of typical code to manipulate a picture on the public
 611      * shared storage:
 612      * </p>
 613      * {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java
 614      * public_picture}
 615      *
 616      * @param type The type of storage directory to return. Should be one of
 617      *            {@link #DIRECTORY_MUSIC}, {@link #DIRECTORY_PODCASTS},
 618      *            {@link #DIRECTORY_RINGTONES}, {@link #DIRECTORY_ALARMS},
 619      *            {@link #DIRECTORY_NOTIFICATIONS}, {@link #DIRECTORY_PICTURES},
 620      *            {@link #DIRECTORY_MOVIES}, {@link #DIRECTORY_DOWNLOADS},
 621      *            {@link #DIRECTORY_DCIM}, or {@link #DIRECTORY_DOCUMENTS}. May not be null.
 622      * @return Returns the File path for the directory. Note that this directory
 623      *         may not yet exist, so you must make sure it exists before using
 624      *         it such as with {@link File#mkdirs File.mkdirs()}.
 625      */
 626     public static File getExternalStoragePublicDirectory(String type) {
 627         throwIfUserRequired();
 628         return sCurrentUser.buildExternalStoragePublicDirs(type)[0];
 629     }
 630
 631     /**
 632      * Returns the path for android-specific data on the SD card.
 633      * @hide
 634      */
 635     public static File[] buildExternalStorageAndroidDataDirs() {
 636         throwIfUserRequired();
 637         return sCurrentUser.buildExternalStorageAndroidDataDirs();
 638     }
 639
 640     /**
 641      * Generates the raw path to an application's data
 642      * @hide
 643      */
 644     public static File[] buildExternalStorageAppDataDirs(String packageName) {
 645         throwIfUserRequired();
 646         return sCurrentUser.buildExternalStorageAppDataDirs(packageName);
 647     }
 648
 649     /**
 650      * Generates the raw path to an application's media
 651      * @hide
 652      */
 653     public static File[] buildExternalStorageAppMediaDirs(String packageName) {
 654         throwIfUserRequired();
 655         return sCurrentUser.buildExternalStorageAppMediaDirs(packageName);
 656     }
 657
 658     /**
 659      * Generates the raw path to an application's OBB files
 660      * @hide
 661      */
 662     public static File[] buildExternalStorageAppObbDirs(String packageName) {
 663         throwIfUserRequired();
 664         return sCurrentUser.buildExternalStorageAppObbDirs(packageName);
 665     }
 666
 667     /**
 668      * Generates the path to an application's files.
 669      * @hide
 670      */
 671     public static File[] buildExternalStorageAppFilesDirs(String packageName) {
 672         throwIfUserRequired();
 673         return sCurrentUser.buildExternalStorageAppFilesDirs(packageName);
 674     }
 675
 676     /**
 677      * Generates the path to an application's cache.
 678      * @hide
 679      */
 680     public static File[] buildExternalStorageAppCacheDirs(String packageName) {
 681         throwIfUserRequired();
 682         return sCurrentUser.buildExternalStorageAppCacheDirs(packageName);
 683     }
 684
 685     /**
 686      * Return the download/cache content directory.
 687      */
 688     public static File getDownloadCacheDirectory() {
 689         return DIR_DOWNLOAD_CACHE;
 690     }
 691
 692     /**
 693      * Unknown storage state, such as when a path isn't backed by known storage
 694      * media.
 695      *
 696      * @see #getExternalStorageState(File)
 697      */
 698     public static final String MEDIA_UNKNOWN = "unknown";
 699
 700     /**
 701      * Storage state if the media is not present.
 702      *
 703      * @see #getExternalStorageState(File)
 704      */
 705     public static final String MEDIA_REMOVED = "removed";
 706
 707     /**
 708      * Storage state if the media is present but not mounted.
 709      *
 710      * @see #getExternalStorageState(File)
 711      */
 712     public static final String MEDIA_UNMOUNTED = "unmounted";
 713
 714     /**
 715      * Storage state if the media is present and being disk-checked.
 716      *
 717      * @see #getExternalStorageState(File)
 718      */
 719     public static final String MEDIA_CHECKING = "checking";
 720
 721     /**
 722      * Storage state if the media is present but is blank or is using an
 723      * unsupported filesystem.
 724      *
 725      * @see #getExternalStorageState(File)
 726      */
 727     public static final String MEDIA_NOFS = "nofs";
 728
 729     /**
 730      * Storage state if the media is present and mounted at its mount point with
 731      * read/write access.
 732      *
 733      * @see #getExternalStorageState(File)
 734      */
 735     public static final String MEDIA_MOUNTED = "mounted";
 736
 737     /**
 738      * Storage state if the media is present and mounted at its mount point with
 739      * read-only access.
 740      *
 741      * @see #getExternalStorageState(File)
 742      */
 743     public static final String MEDIA_MOUNTED_READ_ONLY = "mounted_ro";
 744
 745     /**
 746      * Storage state if the media is present not mounted, and shared via USB
 747      * mass storage.
 748      *
 749      * @see #getExternalStorageState(File)
 750      */
 751     public static final String MEDIA_SHARED = "shared";
 752
 753     /**
 754      * Storage state if the media was removed before it was unmounted.
 755      *
 756      * @see #getExternalStorageState(File)
 757      */
 758     public static final String MEDIA_BAD_REMOVAL = "bad_removal";
 759
 760     /**
 761      * Storage state if the media is present but cannot be mounted. Typically
 762      * this happens if the file system on the media is corrupted.
 763      *
 764      * @see #getExternalStorageState(File)
 765      */
 766     public static final String MEDIA_UNMOUNTABLE = "unmountable";
 767
 768     /**
 769      * Storage state if the media is in the process of being ejected.
 770      *
 771      * @see #getExternalStorageState(File)
 772      */
 773     public static final String MEDIA_EJECTING = "ejecting";
 774
 775     /**
 776      * Returns the current state of the primary shared/external storage media.
 777      *
 778      * @see #getExternalStorageDirectory()
 779      * @return one of {@link #MEDIA_UNKNOWN}, {@link #MEDIA_REMOVED},
 780      *         {@link #MEDIA_UNMOUNTED}, {@link #MEDIA_CHECKING},
 781      *         {@link #MEDIA_NOFS}, {@link #MEDIA_MOUNTED},
 782      *         {@link #MEDIA_MOUNTED_READ_ONLY}, {@link #MEDIA_SHARED},
 783      *         {@link #MEDIA_BAD_REMOVAL}, or {@link #MEDIA_UNMOUNTABLE}.
 784      */
 785     public static String getExternalStorageState() {
 786         final File externalDir = sCurrentUser.getExternalDirs()[0];
 787         return getExternalStorageState(externalDir);
 788     }
 789
 790     /**
 791      * @deprecated use {@link #getExternalStorageState(File)}
 792      */
 793     @Deprecated
 794     public static String getStorageState(File path) {
 795         return getExternalStorageState(path);
 796     }
 797
 798     /**
 799      * Returns the current state of the shared/external storage media at the
 800      * given path.
 801      *
 802      * @return one of {@link #MEDIA_UNKNOWN}, {@link #MEDIA_REMOVED},
 803      *         {@link #MEDIA_UNMOUNTED}, {@link #MEDIA_CHECKING},
 804      *         {@link #MEDIA_NOFS}, {@link #MEDIA_MOUNTED},
 805      *         {@link #MEDIA_MOUNTED_READ_ONLY}, {@link #MEDIA_SHARED},
 806      *         {@link #MEDIA_BAD_REMOVAL}, or {@link #MEDIA_UNMOUNTABLE}.
 807      */
 808     public static String getExternalStorageState(File path) {
 809         final StorageVolume volume = StorageManager.getStorageVolume(path, UserHandle.myUserId());
 810         if (volume != null) {
 811             return volume.getState();
 812         } else {
 813             return MEDIA_UNKNOWN;
 814         }
 815     }
 816
 817     /**
 818      * Returns whether the primary shared/external storage media is physically
 819      * removable.
 820      *
 821      * @return true if the storage device can be removed (such as an SD card),
 822      *         or false if the storage device is built in and cannot be
 823      *         physically removed.
 824      */
 825     public static boolean isExternalStorageRemovable() {
 826         if (isStorageDisabled()) return false;
 827         final File externalDir = sCurrentUser.getExternalDirs()[0];
 828         return isExternalStorageRemovable(externalDir);
 829     }
 830
 831     /**
 832      * Returns whether the shared/external storage media at the given path is
 833      * physically removable.
 834      *
 835      * @return true if the storage device can be removed (such as an SD card),
 836      *         or false if the storage device is built in and cannot be
 837      *         physically removed.
 838      * @throws IllegalArgumentException if the path is not a valid storage
 839      *             device.
 840      */
 841     public static boolean isExternalStorageRemovable(File path) {
 842         final StorageVolume volume = StorageManager.getStorageVolume(path, UserHandle.myUserId());
 843         if (volume != null) {
 844             return volume.isRemovable();
 845         } else {
 846             throw new IllegalArgumentException("Failed to find storage device at " + path);
 847         }
 848     }
 849
 850     /**
 851      * Returns whether the primary shared/external storage media is emulated.
 852      * <p>
 853      * The contents of emulated storage devices are backed by a private user
 854      * data partition, which means there is little benefit to apps storing data
 855      * here instead of the private directories returned by
 856      * {@link Context#getFilesDir()}, etc.
 857      * <p>
 858      * This returns true when emulated storage is backed by either internal
 859      * storage or an adopted storage device.
 860      *
 861      * @see DevicePolicyManager#setStorageEncryption(android.content.ComponentName,
 862      *      boolean)
 863      */
 864     public static boolean isExternalStorageEmulated() {
 865         if (isStorageDisabled()) return false;
 866         final File externalDir = sCurrentUser.getExternalDirs()[0];
 867         return isExternalStorageEmulated(externalDir);
 868     }
 869
 870     /**
 871      * Returns whether the shared/external storage media at the given path is
 872      * emulated.
 873      * <p>
 874      * The contents of emulated storage devices are backed by a private user
 875      * data partition, which means there is little benefit to apps storing data
 876      * here instead of the private directories returned by
 877      * {@link Context#getFilesDir()}, etc.
 878      * <p>
 879      * This returns true when emulated storage is backed by either internal
 880      * storage or an adopted storage device.
 881      *
 882      * @throws IllegalArgumentException if the path is not a valid storage
 883      *             device.
 884      */
 885     public static boolean isExternalStorageEmulated(File path) {
 886         final StorageVolume volume = StorageManager.getStorageVolume(path, UserHandle.myUserId());
 887         if (volume != null) {
 888             return volume.isEmulated();
 889         } else {
 890             throw new IllegalArgumentException("Failed to find storage device at " + path);
 891         }
 892     }
 893
 894     static File getDirectory(String variableName, String defaultPath) {
 895         String path = System.getenv(variableName);
 896         return path == null ? new File(defaultPath) : new File(path);
 897     }
 898
 899     /** {@hide} */
 900     public static void setUserRequired(boolean userRequired) {
 901         sUserRequired = userRequired;
 902     }
 903
 904     private static void throwIfUserRequired() {
 905         if (sUserRequired) {
 906             Log.wtf(TAG, "Path requests must specify a user by using UserEnvironment",
 907                     new Throwable());
 908         }
 909     }
 910
 911     /**
 912      * Append path segments to each given base path, returning result.
 913      *
 914      * @hide
 915      */
 916     public static File[] buildPaths(File[] base, String... segments) {
 917         File[] result = new File[base.length];
 918         for (int i = 0; i < base.length; i++) {
 919             result[i] = buildPath(base[i], segments);
 920         }
 921         return result;
 922     }
 923
 924     /**
 925      * Append path segments to given base path, returning result.
 926      *
 927      * @hide
 928      */
 929     public static File buildPath(File base, String... segments) {
 930         File cur = base;
 931         for (String segment : segments) {
 932             if (cur == null) {
 933                 cur = new File(segment);
 934             } else {
 935                 cur = new File(cur, segment);
 936             }
 937         }
 938         return cur;
 939     }
 940
 941     private static boolean isStorageDisabled() {
 942         return SystemProperties.getBoolean("config.disable_storage", false);
 943     }
 944
 945     /**
 946      * If the given path exists on emulated external storage, return the
 947      * translated backing path hosted on internal storage. This bypasses any
 948      * emulation later, improving performance. This is <em>only</em> suitable
 949      * for read-only access.
 950      * <p>
 951      * Returns original path if given path doesn't meet these criteria. Callers
 952      * must hold {@link android.Manifest.permission#WRITE_MEDIA_STORAGE}
 953      * permission.
 954      *
 955      * @hide
 956      */
 957     public static File maybeTranslateEmulatedPathToInternal(File path) {
 958         return StorageManager.maybeTranslateEmulatedPathToInternal(path);
 959     }
 960 }