Most visited

Recently visited

Added in API level 1

Environment

public class Environment
extends Object

java.lang.Object
   ↳ android.os.Environment


Provides access to environment variables.

Summary

Constants

String MEDIA_BAD_REMOVAL

Storage state if the media was removed before it was unmounted.

String MEDIA_CHECKING

Storage state if the media is present and being disk-checked.

String MEDIA_EJECTING

Storage state if the media is in the process of being ejected.

String MEDIA_MOUNTED

Storage state if the media is present and mounted at its mount point with read/write access.

String MEDIA_MOUNTED_READ_ONLY

Storage state if the media is present and mounted at its mount point with read-only access.

String MEDIA_NOFS

Storage state if the media is present but is blank or is using an unsupported filesystem.

String MEDIA_REMOVED

Storage state if the media is not present.

String MEDIA_SHARED

Storage state if the media is present not mounted, and shared via USB mass storage.

String MEDIA_UNKNOWN

Unknown storage state, such as when a path isn't backed by known storage media.

String MEDIA_UNMOUNTABLE

Storage state if the media is present but cannot be mounted.

String MEDIA_UNMOUNTED

Storage state if the media is present but not mounted.

Fields

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).

public static String DIRECTORY_DCIM

The traditional location for pictures and videos when mounting the device as a camera.

public static String DIRECTORY_DOCUMENTS

Standard directory in which to place documents that have been created by the user.

public static String DIRECTORY_DOWNLOADS

Standard directory in which to place files that have been downloaded by the user.

public static String DIRECTORY_MOVIES

Standard directory in which to place movies that are available to the user.

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.

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).

public static String DIRECTORY_PICTURES

Standard directory in which to place pictures that are available to the user.

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).

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).

Public constructors

Environment()

Public methods

static File getDataDirectory()

Return the user data directory.

static File getDownloadCacheDirectory()

Return the download/cache content directory.

static File getExternalStorageDirectory()

Return the primary shared/external storage directory.

static File getExternalStoragePublicDirectory(String type)

Get a top-level shared/external storage directory for placing files of a particular type.

static String getExternalStorageState()

Returns the current state of the primary shared/external storage media.

static String getExternalStorageState(File path)

Returns the current state of the shared/external storage media at the given path.

static File getRootDirectory()

Return root of the "system" partition holding the core Android OS.

static String getStorageState(File path)

This method was deprecated in API level 21. use getExternalStorageState(File)

static boolean isExternalStorageEmulated()

Returns whether the primary shared/external storage media is emulated.

static boolean isExternalStorageEmulated(File path)

Returns whether the shared/external storage media at the given path is emulated.

static boolean isExternalStorageRemovable()

Returns whether the primary shared/external storage media is physically removable.

static boolean isExternalStorageRemovable(File path)

Returns whether the shared/external storage media at the given path is physically removable.

Inherited methods

From class java.lang.Object

Constants

MEDIA_BAD_REMOVAL

Added in API level 1
String MEDIA_BAD_REMOVAL

Storage state if the media was removed before it was unmounted.

See also:

Constant Value: "bad_removal"

MEDIA_CHECKING

Added in API level 3
String MEDIA_CHECKING

Storage state if the media is present and being disk-checked.

See also:

Constant Value: "checking"

MEDIA_EJECTING

Added in API level 23
String MEDIA_EJECTING

Storage state if the media is in the process of being ejected.

See also:

Constant Value: "ejecting"

MEDIA_MOUNTED

Added in API level 1
String MEDIA_MOUNTED

Storage state if the media is present and mounted at its mount point with read/write access.

See also:

Constant Value: "mounted"

MEDIA_MOUNTED_READ_ONLY

Added in API level 1
String MEDIA_MOUNTED_READ_ONLY

Storage state if the media is present and mounted at its mount point with read-only access.

See also:

Constant Value: "mounted_ro"

MEDIA_NOFS

Added in API level 3
String MEDIA_NOFS

Storage state if the media is present but is blank or is using an unsupported filesystem.

See also:

Constant Value: "nofs"

MEDIA_REMOVED

Added in API level 1
String MEDIA_REMOVED

Storage state if the media is not present.

See also:

Constant Value: "removed"

MEDIA_SHARED

Added in API level 1
String MEDIA_SHARED

Storage state if the media is present not mounted, and shared via USB mass storage.

See also:

Constant Value: "shared"

MEDIA_UNKNOWN

Added in API level 19
String MEDIA_UNKNOWN

Unknown storage state, such as when a path isn't backed by known storage media.

See also:

Constant Value: "unknown"

MEDIA_UNMOUNTABLE

Added in API level 1
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.

See also:

Constant Value: "unmountable"

MEDIA_UNMOUNTED

Added in API level 1
String MEDIA_UNMOUNTED

Storage state if the media is present but not mounted.

See also:

Constant Value: "unmounted"

Fields

DIRECTORY_ALARMS

Added in API level 8
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 DIRECTORY_MUSIC, DIRECTORY_PODCASTS, DIRECTORY_NOTIFICATIONS, and DIRECTORY_RINGTONES as a series of directories to categories a particular audio file as more than one type.

DIRECTORY_DCIM

Added in API level 8
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.

DIRECTORY_DOCUMENTS

Added in API level 19
String DIRECTORY_DOCUMENTS

Standard directory in which to place documents that have been created by the user.

DIRECTORY_DOWNLOADS

Added in API level 8
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.

DIRECTORY_MOVIES

Added in API level 8
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.

DIRECTORY_MUSIC

Added in API level 8
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 DIRECTORY_PODCASTS, DIRECTORY_NOTIFICATIONS, DIRECTORY_ALARMS, and DIRECTORY_RINGTONES as a series of directories to categories a particular audio file as more than one type.

DIRECTORY_NOTIFICATIONS

Added in API level 8
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 DIRECTORY_MUSIC, DIRECTORY_PODCASTS, DIRECTORY_ALARMS, and DIRECTORY_RINGTONES as a series of directories to categories a particular audio file as more than one type.

DIRECTORY_PICTURES

Added in API level 8
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.

DIRECTORY_PODCASTS

Added in API level 8
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 DIRECTORY_MUSIC, DIRECTORY_NOTIFICATIONS, DIRECTORY_ALARMS, and DIRECTORY_RINGTONES as a series of directories to categories a particular audio file as more than one type.

DIRECTORY_RINGTONES

Added in API level 8
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 DIRECTORY_MUSIC, DIRECTORY_PODCASTS, DIRECTORY_NOTIFICATIONS, and DIRECTORY_ALARMS as a series of directories to categories a particular audio file as more than one type.

Public constructors

Environment

Added in API level 1
Environment ()

Public methods

getDataDirectory

Added in API level 1
File getDataDirectory ()

Return the user data directory.

Returns
File

getDownloadCacheDirectory

Added in API level 1
File getDownloadCacheDirectory ()

Return the download/cache content directory.

Returns
File

getExternalStorageDirectory

Added in API level 1
File getExternalStorageDirectory ()

Return the primary shared/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 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 UserManager), each user has their own isolated shared storage. Applications only have access to the shared storage for the user they're running as.

In devices with multiple shared/external storage directories, this directory represents the primary storage that the user will interact with. Access to secondary storage is available through getExternalFilesDirs(String), getExternalCacheDirs(), and getExternalMediaDirs().

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 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 getExternalStoragePublicDirectory(String).

Writing to this path requires the WRITE_EXTERNAL_STORAGE permission, and starting in KITKAT, read access requires the READ_EXTERNAL_STORAGE permission, which is automatically granted if you hold the write permission.

Starting in KITKAT, if your application only needs to store internal data, consider using getExternalFilesDir(String), getExternalCacheDir(), or getExternalMediaDirs(), 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:

BroadcastReceiver mExternalStorageReceiver;
boolean mExternalStorageAvailable = false;
boolean mExternalStorageWriteable = false;

void updateExternalStorageState() {
    String state = Environment.getExternalStorageState();
    if (Environment.MEDIA_MOUNTED.equals(state)) {
        mExternalStorageAvailable = mExternalStorageWriteable = true;
    } else if (Environment.MEDIA_MOUNTED_READ_ONLY.equals(state)) {
        mExternalStorageAvailable = true;
        mExternalStorageWriteable = false;
    } else {
        mExternalStorageAvailable = mExternalStorageWriteable = false;
    }
    handleExternalStorageState(mExternalStorageAvailable,
            mExternalStorageWriteable);
}

void startWatchingExternalStorage() {
    mExternalStorageReceiver = new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            Log.i("test", "Storage: " + intent.getData());
            updateExternalStorageState();
        }
    };
    IntentFilter filter = new IntentFilter();
    filter.addAction(Intent.ACTION_MEDIA_MOUNTED);
    filter.addAction(Intent.ACTION_MEDIA_REMOVED);
    registerReceiver(mExternalStorageReceiver, filter);
    updateExternalStorageState();
}

void stopWatchingExternalStorage() {
    unregisterReceiver(mExternalStorageReceiver);
}

Returns
File

See also:

getExternalStoragePublicDirectory

Added in API level 8
File getExternalStoragePublicDirectory (String type)

Get a top-level shared/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 UserManager), each user has their own isolated shared storage. Applications only have access to the shared storage for the user they're running as.

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

void createExternalStoragePublicPicture() {
    // Create a path where we will place our picture in the user's
    // public pictures directory.  Note that you should be careful about
    // what you place here, since the user often manages these files.  For
    // pictures and other media owned by the application, consider
    // Context.getExternalMediaDir().
    File path = Environment.getExternalStoragePublicDirectory(
            Environment.DIRECTORY_PICTURES);
    File file = new File(path, "DemoPicture.jpg");

    try {
        // Make sure the Pictures directory exists.
        path.mkdirs();

        // Very simple code to copy a picture from the application's
        // resource into the external file.  Note that this code does
        // no error checking, and assumes the picture is small (does not
        // try to copy it in chunks).  Note that if external storage is
        // not currently mounted this will silently fail.
        InputStream is = getResources().openRawResource(R.drawable.balloons);
        OutputStream os = new FileOutputStream(file);
        byte[] data = new byte[is.available()];
        is.read(data);
        os.write(data);
        is.close();
        os.close();

        // Tell the media scanner about the new file so that it is
        // immediately available to the user.
        MediaScannerConnection.scanFile(this,
                new String[] { file.toString() }, null,
                new MediaScannerConnection.OnScanCompletedListener() {
            public void onScanCompleted(String path, Uri uri) {
                Log.i("ExternalStorage", "Scanned " + path + ":");
                Log.i("ExternalStorage", "-> uri=" + uri);
            }
        });
    } catch (IOException e) {
        // Unable to create file, likely because external storage is
        // not currently mounted.
        Log.w("ExternalStorage", "Error writing " + file, e);
    }
}

void deleteExternalStoragePublicPicture() {
    // Create a path where we will place our picture in the user's
    // public pictures directory and delete the file.  If external
    // storage is not currently mounted this will fail.
    File path = Environment.getExternalStoragePublicDirectory(
            Environment.DIRECTORY_PICTURES);
    File file = new File(path, "DemoPicture.jpg");
    file.delete();
}

boolean hasExternalStoragePublicPicture() {
    // Create a path where we will place our picture in the user's
    // public pictures directory and check if the file exists.  If
    // external storage is not currently mounted this will think the
    // picture doesn't exist.
    File path = Environment.getExternalStoragePublicDirectory(
            Environment.DIRECTORY_PICTURES);
    File file = new File(path, "DemoPicture.jpg");
    return file.exists();
}

Parameters
type String: The type of storage directory to return. Should be one of DIRECTORY_MUSIC, DIRECTORY_PODCASTS, DIRECTORY_RINGTONES, DIRECTORY_ALARMS, DIRECTORY_NOTIFICATIONS, DIRECTORY_PICTURES, DIRECTORY_MOVIES, DIRECTORY_DOWNLOADS, DIRECTORY_DCIM, or DIRECTORY_DOCUMENTS. May not be null.
Returns
File 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 File.mkdirs().

getExternalStorageState

Added in API level 1
String getExternalStorageState ()

Returns the current state of the primary shared/external storage media.

Returns
String one of MEDIA_UNKNOWN, MEDIA_REMOVED, MEDIA_UNMOUNTED, MEDIA_CHECKING, MEDIA_NOFS, MEDIA_MOUNTED, MEDIA_MOUNTED_READ_ONLY, MEDIA_SHARED, MEDIA_BAD_REMOVAL, or MEDIA_UNMOUNTABLE.

See also:

getExternalStorageState

Added in API level 21
String getExternalStorageState (File path)

Returns the current state of the shared/external storage media at the given path.

Parameters
path File
Returns
String one of MEDIA_UNKNOWN, MEDIA_REMOVED, MEDIA_UNMOUNTED, MEDIA_CHECKING, MEDIA_NOFS, MEDIA_MOUNTED, MEDIA_MOUNTED_READ_ONLY, MEDIA_SHARED, MEDIA_BAD_REMOVAL, or MEDIA_UNMOUNTABLE.

getRootDirectory

Added in API level 1
File getRootDirectory ()

Return root of the "system" partition holding the core Android OS. Always present and mounted read-only.

Returns
File

getStorageState

Added in API level 19
String getStorageState (File path)

This method was deprecated in API level 21.
use getExternalStorageState(File)

Parameters
path File
Returns
String

isExternalStorageEmulated

Added in API level 11
boolean isExternalStorageEmulated ()

Returns whether the primary shared/external storage media is emulated.

The contents of emulated storage devices are backed by a private user data partition, which means there is little benefit to apps storing data here instead of the private directories returned by getFilesDir(), etc.

This returns true when emulated storage is backed by either internal storage or an adopted storage device.

Returns
boolean

See also:

isExternalStorageEmulated

Added in API level 21
boolean isExternalStorageEmulated (File path)

Returns whether the shared/external storage media at the given path is emulated.

The contents of emulated storage devices are backed by a private user data partition, which means there is little benefit to apps storing data here instead of the private directories returned by getFilesDir(), etc.

This returns true when emulated storage is backed by either internal storage or an adopted storage device.

Parameters
path File
Returns
boolean
Throws
IllegalArgumentException if the path is not a valid storage device.

isExternalStorageRemovable

Added in API level 9
boolean isExternalStorageRemovable ()

Returns whether the primary shared/external storage media is physically removable.

Returns
boolean 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.

isExternalStorageRemovable

Added in API level 21
boolean isExternalStorageRemovable (File path)

Returns whether the shared/external storage media at the given path is physically removable.

Parameters
path File
Returns
boolean 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.

Hooray!