FileDocCategorySizeDatePackage
Environment.javaAPI DocAndroid 5.1 API34498Thu Mar 12 22:22:10 GMT 2015android.os

Environment

public class Environment extends Object
Provides access to environment variables.

Fields Summary
private static final String
TAG
private static final String
ENV_EXTERNAL_STORAGE
private static final String
ENV_EMULATED_STORAGE_SOURCE
private static final String
ENV_EMULATED_STORAGE_TARGET
private static final String
ENV_MEDIA_STORAGE
private static final String
ENV_SECONDARY_STORAGE
private static final String
ENV_ANDROID_ROOT
private static final String
ENV_OEM_ROOT
private static final String
ENV_VENDOR_ROOT
public static final String
DIR_ANDROID
{@hide}
private static final String
DIR_DATA
private static final String
DIR_MEDIA
private static final String
DIR_OBB
private static final String
DIR_FILES
private static final String
DIR_CACHE
public static final String
DIRECTORY_ANDROID
{@hide}
private static final File
DIR_ANDROID_ROOT
private static final File
DIR_OEM_ROOT
private static final File
DIR_VENDOR_ROOT
private static final File
DIR_MEDIA_STORAGE
private static final String
CANONCIAL_EMULATED_STORAGE_TARGET
private static final String
SYSTEM_PROPERTY_EFS_ENABLED
private static UserEnvironment
sCurrentUser
private static boolean
sUserRequired
private static final File
DATA_DIRECTORY
private static final File
SECURE_DATA_DIRECTORY
private static final File
DOWNLOAD_CACHE_DIRECTORY
public static String
DIRECTORY_MUSIC
Standard directory in which to place any audio files that should be in the regular list of music for the user. This may be combined with {@link #DIRECTORY_PODCASTS}, {@link #DIRECTORY_NOTIFICATIONS}, {@link #DIRECTORY_ALARMS}, and {@link #DIRECTORY_RINGTONES} as a series of directories to categories a particular audio file as more than one type.
public static String
DIRECTORY_PODCASTS
Standard directory in which to place any audio files that should be in the list of podcasts that the user can select (not as regular music). This may be combined with {@link #DIRECTORY_MUSIC}, {@link #DIRECTORY_NOTIFICATIONS}, {@link #DIRECTORY_ALARMS}, and {@link #DIRECTORY_RINGTONES} as a series of directories to categories a particular audio file as more than one type.
public static String
DIRECTORY_RINGTONES
Standard directory in which to place any audio files that should be in the list of ringtones that the user can select (not as regular music). This may be combined with {@link #DIRECTORY_MUSIC}, {@link #DIRECTORY_PODCASTS}, {@link #DIRECTORY_NOTIFICATIONS}, and {@link #DIRECTORY_ALARMS} as a series of directories to categories a particular audio file as more than one type.
public static String
DIRECTORY_ALARMS
Standard directory in which to place any audio files that should be in the list of alarms that the user can select (not as regular music). This may be combined with {@link #DIRECTORY_MUSIC}, {@link #DIRECTORY_PODCASTS}, {@link #DIRECTORY_NOTIFICATIONS}, and {@link #DIRECTORY_RINGTONES} as a series of directories to categories a particular audio file as more than one type.
public static String
DIRECTORY_NOTIFICATIONS
Standard directory in which to place any audio files that should be in the list of notifications that the user can select (not as regular music). This may be combined with {@link #DIRECTORY_MUSIC}, {@link #DIRECTORY_PODCASTS}, {@link #DIRECTORY_ALARMS}, and {@link #DIRECTORY_RINGTONES} as a series of directories to categories a particular audio file as more than one type.
public static String
DIRECTORY_PICTURES
Standard directory in which to place pictures that are available to the user. Note that this is primarily a convention for the top-level public directory, as the media scanner will find and collect pictures in any directory.
public static String
DIRECTORY_MOVIES
Standard directory in which to place movies that are available to the user. Note that this is primarily a convention for the top-level public directory, as the media scanner will find and collect movies in any directory.
public static String
DIRECTORY_DOWNLOADS
Standard directory in which to place files that have been downloaded by the user. Note that this is primarily a convention for the top-level public directory, you are free to download files anywhere in your own private directories. Also note that though the constant here is named DIRECTORY_DOWNLOADS (plural), the actual file name is non-plural for backwards compatibility reasons.
public static String
DIRECTORY_DCIM
The traditional location for pictures and videos when mounting the device as a camera. Note that this is primarily a convention for the top-level public directory, as this convention makes no sense elsewhere.
public static String
DIRECTORY_DOCUMENTS
Standard directory in which to place documents that have been created by the user.
public static final String
MEDIA_UNKNOWN
Unknown storage state, such as when a path isn't backed by known storage media.
public static final String
MEDIA_REMOVED
Storage state if the media is not present.
public static final String
MEDIA_UNMOUNTED
Storage state if the media is present but not mounted.
public static final String
MEDIA_CHECKING
Storage state if the media is present and being disk-checked.
public static final String
MEDIA_NOFS
Storage state if the media is present but is blank or is using an unsupported filesystem.
public static final String
MEDIA_MOUNTED
Storage state if the media is present and mounted at its mount point with read/write access.
public static final String
MEDIA_MOUNTED_READ_ONLY
Storage state if the media is present and mounted at its mount point with read-only access.
public static final String
MEDIA_SHARED
Storage state if the media is present not mounted, and shared via USB mass storage.
public static final String
MEDIA_BAD_REMOVAL
Storage state if the media was removed before it was unmounted.
public static final String
MEDIA_UNMOUNTABLE
Storage state if the media is present but cannot be mounted. Typically this happens if the file system on the media is corrupted.
Constructors Summary
Methods Summary
public static java.io.File[]buildExternalStorageAndroidDataDirs()
Returns the path for android-specific data on the SD card.

hide

        throwIfUserRequired();
        return sCurrentUser.buildExternalStorageAndroidDataDirs();
public static java.io.File[]buildExternalStorageAppCacheDirs(java.lang.String packageName)
Generates the path to an application's cache.

hide

        throwIfUserRequired();
        return sCurrentUser.buildExternalStorageAppCacheDirs(packageName);
public static java.io.File[]buildExternalStorageAppDataDirs(java.lang.String packageName)
Generates the raw path to an application's data

hide

        throwIfUserRequired();
        return sCurrentUser.buildExternalStorageAppDataDirs(packageName);
public static java.io.File[]buildExternalStorageAppFilesDirs(java.lang.String packageName)
Generates the path to an application's files.

hide

        throwIfUserRequired();
        return sCurrentUser.buildExternalStorageAppFilesDirs(packageName);
public static java.io.File[]buildExternalStorageAppMediaDirs(java.lang.String packageName)
Generates the raw path to an application's media

hide

        throwIfUserRequired();
        return sCurrentUser.buildExternalStorageAppMediaDirs(packageName);
public static java.io.File[]buildExternalStorageAppObbDirs(java.lang.String packageName)
Generates the raw path to an application's OBB files

hide

        throwIfUserRequired();
        return sCurrentUser.buildExternalStorageAppObbDirs(packageName);
public static java.io.FilebuildPath(java.io.File base, java.lang.String segments)
Append path segments to given base path, returning result.

hide

        File cur = base;
        for (String segment : segments) {
            if (cur == null) {
                cur = new File(segment);
            } else {
                cur = new File(cur, segment);
            }
        }
        return cur;
public static java.io.File[]buildPaths(java.io.File[] base, java.lang.String segments)
Append path segments to each given base path, returning result.

hide

        File[] result = new File[base.length];
        for (int i = 0; i < base.length; i++) {
            result[i] = buildPath(base[i], segments);
        }
        return result;
private static java.lang.StringgetCanonicalPathOrNull(java.lang.String variableName)

        String path = System.getenv(variableName);
        if (path == null) {
            return null;
        }
        try {
            return new File(path).getCanonicalPath();
        } catch (IOException e) {
            Log.w(TAG, "Unable to resolve canonical path for " + path);
            return null;
        }
public static java.io.FilegetDataDirectory()
Return the user data directory.


              
        
        return DATA_DIRECTORY;
static java.io.FilegetDirectory(java.lang.String variableName, java.lang.String defaultPath)

        String path = System.getenv(variableName);
        return path == null ? new File(defaultPath) : new File(path);
public static java.io.FilegetDownloadCacheDirectory()
Return the download/cache content directory.

        return DOWNLOAD_CACHE_DIRECTORY;
public static java.io.FilegetEmulatedStorageObbSource()
{@hide}

        // /mnt/shell/emulated/obb
        return new File(System.getenv(ENV_EMULATED_STORAGE_SOURCE), DIR_OBB);
public static java.io.FilegetEmulatedStorageSource(int userId)
{@hide}

        // /mnt/shell/emulated/0
        return new File(System.getenv(ENV_EMULATED_STORAGE_SOURCE), String.valueOf(userId));
public static java.io.FilegetExternalStorageDirectory()
Return the primary external storage directory. This directory may not currently be accessible if it has been mounted by the user on their computer, has been removed from the device, or some other problem has happened. You can determine its current state with {@link #getExternalStorageState()}.

Note: don't be confused by the word "external" here. This directory can better be thought as media/shared storage. It is a filesystem that can hold a relatively large amount of data and that is shared across all applications (does not enforce permissions). Traditionally this is an SD card, but it may also be implemented as built-in storage in a device that is distinct from the protected internal storage and can be mounted as a filesystem on a computer.

On devices with multiple users (as described by {@link UserManager}), each user has their own isolated external storage. Applications only have access to the external storage for the user they're running as.

In devices with multiple "external" storage directories, this directory represents the "primary" external storage that the user will interact with. Access to secondary storage is available through

Applications should not directly use this top-level directory, in order to avoid polluting the user's root namespace. Any files that are private to the application should be placed in a directory returned by {@link android.content.Context#getExternalFilesDir Context.getExternalFilesDir}, which the system will take care of deleting if the application is uninstalled. Other shared files should be placed in one of the directories returned by {@link #getExternalStoragePublicDirectory}.

Writing to this path requires the {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} permission, and starting in read access requires the {@link android.Manifest.permission#READ_EXTERNAL_STORAGE} permission, which is automatically granted if you hold the write permission.

Starting in {@link android.os.Build.VERSION_CODES#KITKAT}, if your application only needs to store internal data, consider using {@link Context#getExternalFilesDir(String)} or {@link Context#getExternalCacheDir()}, which require no permissions to read or write.

This path may change between platform versions, so applications should only persist relative paths.

Here is an example of typical code to monitor the state of external storage:

{@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java monitor_storage}

see
#getExternalStorageState()
see
#isExternalStorageRemovable()

        throwIfUserRequired();
        return sCurrentUser.getExternalDirsForApp()[0];
public static java.io.FilegetExternalStoragePublicDirectory(java.lang.String type)
Get a top-level public external storage directory for placing files of a particular type. This is where the user will typically place and manage their own files, so you should be careful about what you put here to ensure you don't erase their files or get in the way of their own organization.

On devices with multiple users (as described by {@link UserManager}), each user has their own isolated external storage. Applications only have access to the external storage for the user they're running as.

Here is an example of typical code to manipulate a picture on the public external storage:

{@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java public_picture}

param
type The type of storage directory to return. Should be one of {@link #DIRECTORY_MUSIC}, {@link #DIRECTORY_PODCASTS}, {@link #DIRECTORY_RINGTONES}, {@link #DIRECTORY_ALARMS}, {@link #DIRECTORY_NOTIFICATIONS}, {@link #DIRECTORY_PICTURES}, {@link #DIRECTORY_MOVIES}, {@link #DIRECTORY_DOWNLOADS}, or {@link #DIRECTORY_DCIM}. May not be null.
return
Returns the File path for the directory. Note that this directory may not yet exist, so you must make sure it exists before using it such as with {@link File#mkdirs File.mkdirs()}.


                                                                                                                                                                                             
         
        throwIfUserRequired();
        return sCurrentUser.buildExternalStoragePublicDirs(type)[0];
public static java.lang.StringgetExternalStorageState()
Returns the current state of the primary "external" storage device.

see
#getExternalStorageDirectory()
return
one of {@link #MEDIA_UNKNOWN}, {@link #MEDIA_REMOVED}, {@link #MEDIA_UNMOUNTED}, {@link #MEDIA_CHECKING}, {@link #MEDIA_NOFS}, {@link #MEDIA_MOUNTED}, {@link #MEDIA_MOUNTED_READ_ONLY}, {@link #MEDIA_SHARED}, {@link #MEDIA_BAD_REMOVAL}, or {@link #MEDIA_UNMOUNTABLE}.


                                                                              
        
        final File externalDir = sCurrentUser.getExternalDirsForApp()[0];
        return getExternalStorageState(externalDir);
public static java.lang.StringgetExternalStorageState(java.io.File path)
Returns the current state of the storage device that provides the given path.

return
one of {@link #MEDIA_UNKNOWN}, {@link #MEDIA_REMOVED}, {@link #MEDIA_UNMOUNTED}, {@link #MEDIA_CHECKING}, {@link #MEDIA_NOFS}, {@link #MEDIA_MOUNTED}, {@link #MEDIA_MOUNTED_READ_ONLY}, {@link #MEDIA_SHARED}, {@link #MEDIA_BAD_REMOVAL}, or {@link #MEDIA_UNMOUNTABLE}.

        final StorageVolume volume = getStorageVolume(path);
        if (volume != null) {
            final IMountService mountService = IMountService.Stub.asInterface(
                    ServiceManager.getService("mount"));
            try {
                return mountService.getVolumeState(volume.getPath());
            } catch (RemoteException e) {
            }
        }

        return Environment.MEDIA_UNKNOWN;
public static java.io.FilegetLegacyExternalStorageDirectory()
{@hide}

        return new File(System.getenv(ENV_EXTERNAL_STORAGE));
public static java.io.FilegetLegacyExternalStorageObbDirectory()
{@hide}

        return buildPath(getLegacyExternalStorageDirectory(), DIR_ANDROID, DIR_OBB);
public static java.io.FilegetMediaStorageDirectory()
Return directory used for internal media storage, which is protected by {@link android.Manifest.permission#WRITE_MEDIA_STORAGE}.

hide

        throwIfUserRequired();
        return sCurrentUser.getMediaDir();
public static java.io.FilegetOemDirectory()
Return root directory of the "oem" partition holding OEM customizations, if any. If present, the partition is mounted read-only.

hide

        return DIR_OEM_ROOT;
public static java.io.FilegetRootDirectory()
Return root of the "system" partition holding the core Android OS. Always present and mounted read-only.

        return DIR_ANDROID_ROOT;
public static java.io.FilegetSecureDataDirectory()
Gets the data directory for secure storage. If Encrypted File system is enabled, it returns an encrypted directory (/data/secure). Otherwise, it returns the unencrypted /data directory.

return
File object representing the data directory for secure storage.
hide

        if (isEncryptedFilesystemEnabled()) {
            return SECURE_DATA_DIRECTORY;
        } else {
            return DATA_DIRECTORY;
        }
public static java.lang.StringgetStorageState(java.io.File path)

deprecated
use {@link #getExternalStorageState(File)}

        return getExternalStorageState(path);
private static android.os.storage.StorageVolumegetStorageVolume(java.io.File path)

        try {
            path = path.getCanonicalFile();
        } catch (IOException e) {
            return null;
        }

        try {
            final IMountService mountService = IMountService.Stub.asInterface(
                    ServiceManager.getService("mount"));
            final StorageVolume[] volumes = mountService.getVolumeList();
            for (StorageVolume volume : volumes) {
                if (FileUtils.contains(volume.getPathFile(), path)) {
                    return volume;
                }
            }
        } catch (RemoteException e) {
        }

        return null;
public static java.io.FilegetSystemSecureDirectory()
Gets the system directory available for secure storage. If Encrypted File system is enabled, it returns an encrypted directory (/data/secure/system). Otherwise, it returns the unencrypted /data/system directory.

return
File object representing the secure storage system directory.
hide

        if (isEncryptedFilesystemEnabled()) {
            return new File(SECURE_DATA_DIRECTORY, "system");
        } else {
            return new File(DATA_DIRECTORY, "system");
        }
public static java.io.FilegetUserConfigDirectory(int userId)
Returns the config directory for a user. This is for use by system services to store files relating to the user which should be readable by any app running as that user.

hide

        return new File(new File(new File(
                getDataDirectory(), "misc"), "user"), Integer.toString(userId));
public static java.io.FilegetUserSystemDirectory(int userId)
Return the system directory for a user. This is for use by system services to store files relating to the user. This directory will be automatically deleted when the user is removed.

hide

        return new File(new File(getSystemSecureDirectory(), "users"), Integer.toString(userId));
public static java.io.FilegetVendorDirectory()
Return root directory of the "vendor" partition that holds vendor-provided software that should persist across simple reflashing of the "system" partition.

hide

        return DIR_VENDOR_ROOT;
public static voidinitForCurrentUser()
{@hide}


     
        initForCurrentUser();
    
        final int userId = UserHandle.myUserId();
        sCurrentUser = new UserEnvironment(userId);
public static booleanisEncryptedFilesystemEnabled()
Returns whether the Encrypted File System feature is enabled on the device or not.

return
true if Encrypted File System feature is enabled, false if disabled.
hide

        return SystemProperties.getBoolean(SYSTEM_PROPERTY_EFS_ENABLED, false);
public static booleanisExternalStorageEmulated()
Returns whether the primary "external" storage device is emulated. If true, data stored on this device will be stored on a portion of the internal storage system.

see
DevicePolicyManager#setStorageEncryption(android.content.ComponentName, boolean)

        if (isStorageDisabled()) return false;
        final File externalDir = sCurrentUser.getExternalDirsForApp()[0];
        return isExternalStorageEmulated(externalDir);
public static booleanisExternalStorageEmulated(java.io.File path)
Returns whether the storage device that provides the given path is emulated. If true, data stored on this device will be stored on a portion of the internal storage system.

throws
IllegalArgumentException if the path is not a valid storage device.

        final StorageVolume volume = getStorageVolume(path);
        if (volume != null) {
            return volume.isEmulated();
        } else {
            throw new IllegalArgumentException("Failed to find storage device at " + path);
        }
public static booleanisExternalStorageRemovable()
Returns whether the primary "external" storage device is removable.

return
true if the storage device can be removed (such as an SD card), or false if the storage device is built in and cannot be physically removed.

        if (isStorageDisabled()) return false;
        final File externalDir = sCurrentUser.getExternalDirsForApp()[0];
        return isExternalStorageRemovable(externalDir);
public static booleanisExternalStorageRemovable(java.io.File path)
Returns whether the storage device that provides the given path is removable.

return
true if the storage device can be removed (such as an SD card), or false if the storage device is built in and cannot be physically removed.
throws
IllegalArgumentException if the path is not a valid storage device.

        final StorageVolume volume = getStorageVolume(path);
        if (volume != null) {
            return volume.isRemovable();
        } else {
            throw new IllegalArgumentException("Failed to find storage device at " + path);
        }
private static booleanisStorageDisabled()

        return SystemProperties.getBoolean("config.disable_storage", false);
public static java.io.FilemaybeTranslateEmulatedPathToInternal(java.io.File path)
If the given path exists on emulated external storage, return the translated backing path hosted on internal storage. This bypasses any emulation later, improving performance. This is only suitable for read-only access.

Returns original path if given path doesn't meet these criteria. Callers must hold {@link android.Manifest.permission#WRITE_MEDIA_STORAGE} permission.

hide

        // Fast return if not emulated, or missing variables
        if (!Environment.isExternalStorageEmulated()
                || CANONCIAL_EMULATED_STORAGE_TARGET == null) {
            return path;
        }

        try {
            final String rawPath = path.getCanonicalPath();
            if (rawPath.startsWith(CANONCIAL_EMULATED_STORAGE_TARGET)) {
                final File internalPath = new File(DIR_MEDIA_STORAGE,
                        rawPath.substring(CANONCIAL_EMULATED_STORAGE_TARGET.length()));
                if (internalPath.exists()) {
                    return internalPath;
                }
            }
        } catch (IOException e) {
            Log.w(TAG, "Failed to resolve canonical path for " + path);
        }

        // Unable to translate to internal path; use original
        return path;
public static voidsetUserRequired(boolean userRequired)
{@hide}

        sUserRequired = userRequired;
private static voidthrowIfUserRequired()

        if (sUserRequired) {
            Log.wtf(TAG, "Path requests must specify a user by using UserEnvironment",
                    new Throwable());
        }