java.lang.Object | |
↳ | android.os.Environment |
Provides access to environment variables.
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_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 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
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). | |||||||||
|
DIRECTORY_DCIM | The traditional location for pictures and videos when mounting the device as a camera. | |||||||||
|
DIRECTORY_DOCUMENTS | Standard directory in which to place documents that have been created by the user. | |||||||||
|
DIRECTORY_DOWNLOADS | Standard directory in which to place files that have been downloaded by the user. | |||||||||
|
DIRECTORY_MOVIES | Standard directory in which to place movies that are available to the user. | |||||||||
|
DIRECTORY_MUSIC | Standard directory in which to place any audio files that should be in the regular list of music for the user. | |||||||||
|
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). | |||||||||
|
DIRECTORY_PICTURES | Standard directory in which to place pictures that are available to the user. | |||||||||
|
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). | |||||||||
|
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 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
Return the user data directory.
|
||||||||||
|
Return the download/cache content directory.
|
||||||||||
|
Return the primary external storage directory.
|
||||||||||
|
Get a top-level public external storage directory for placing files of
a particular type.
|
||||||||||
|
Returns the current state of the primary "external" storage device.
|
||||||||||
|
Gets the Android root directory.
|
||||||||||
|
Returns the current state of the storage device that provides the given
path.
|
||||||||||
|
Returns whether the device has an external storage device which is
emulated.
|
||||||||||
|
Returns whether the primary "external" storage device is removable.
|
[Expand]
Inherited Methods
|
|||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
Storage state if the media was removed before it was unmounted.
Storage state if the media is present and being disk-checked.
Storage state if the media is present and mounted at its mount point with read/write access.
Storage state if the media is present and mounted at its mount point with read-only access.
Storage state if the media is present but is blank or is using an unsupported filesystem.
Storage state if the media is present not mounted, and shared via USB mass storage.
Unknown storage state, such as when a path isn't backed by known storage media.
Storage state if the media is present but cannot be mounted. Typically this happens if the file system on the media is corrupted.
Storage state if the media is present but not mounted.
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.
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.
Standard directory in which to place documents that have been created by the user.
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.
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.
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.
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.
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.
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.
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.
Return the download/cache content directory.
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
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 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
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 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)
or
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:
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); }
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
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:
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(); }
type |
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
, or
DIRECTORY_DCIM
. May not be null.
|
---|
File.mkdirs()
.
Returns the current state of the primary "external" storage device.
MEDIA_UNKNOWN
,
MEDIA_REMOVED
,
MEDIA_UNMOUNTED
,
MEDIA_CHECKING
,
MEDIA_NOFS
,
MEDIA_MOUNTED
,
MEDIA_MOUNTED_READ_ONLY
,
MEDIA_SHARED
,
MEDIA_BAD_REMOVAL
, or
MEDIA_UNMOUNTABLE
.
Returns the current state of the storage device that provides the given path.
MEDIA_UNKNOWN
,
MEDIA_REMOVED
,
MEDIA_UNMOUNTED
,
MEDIA_CHECKING
,
MEDIA_NOFS
,
MEDIA_MOUNTED
,
MEDIA_MOUNTED_READ_ONLY
,
MEDIA_SHARED
,
MEDIA_BAD_REMOVAL
, or
MEDIA_UNMOUNTABLE
.
Returns whether the device has an external storage device which is
emulated. If true, the device does not have real external storage, and the directory
returned by
getExternalStorageDirectory()
will be allocated using a portion of
the internal storage system.
Certain system services, such as the package manager, use this to determine where to install an application.
Emulated external storage may also be encrypted - see
setStorageEncryption(android.content.ComponentName, boolean)
for additional details.
Returns whether the primary "external" storage device is removable. If true is returned, this device is for example an SD card that the user can remove. If false is returned, the storage is built into the device and can not be physically removed.
See
getExternalStorageDirectory()
for more information.