public class Environment extends Object
Modifier and Type | Class and Description |
---|---|
static class |
Environment.UserEnvironment |
Modifier and Type | Field and Description |
---|---|
static String |
DIR_ANDROID |
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).
|
static String |
DIRECTORY_ANDROID
Deprecated.
|
static String |
DIRECTORY_DCIM
The traditional location for pictures and videos when mounting the
device as a camera.
|
static String |
DIRECTORY_DOCUMENTS
Standard directory in which to place documents that have been created by
the user.
|
static String |
DIRECTORY_DOWNLOADS
Standard directory in which to place files that have been downloaded by
the user.
|
static String |
DIRECTORY_MOVIES
Standard directory in which to place movies that are available to
the user.
|
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.
|
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).
|
static String |
DIRECTORY_PICTURES
Standard directory in which to place pictures that are available to
the user.
|
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).
|
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).
|
static String |
MEDIA_BAD_REMOVAL
Storage state if the media was removed before it was unmounted.
|
static String |
MEDIA_CHECKING
Storage state if the media is present and being disk-checked.
|
static String |
MEDIA_EJECTING
Storage state if the media is in the process of being ejected.
|
static String |
MEDIA_MOUNTED
Storage state if the media is present and mounted at its mount point with
read/write access.
|
static String |
MEDIA_MOUNTED_READ_ONLY
Storage state if the media is present and mounted at its mount point with
read-only access.
|
static String |
MEDIA_NOFS
Storage state if the media is present but is blank or is using an
unsupported filesystem.
|
static String |
MEDIA_REMOVED
Storage state if the media is not present.
|
static String |
MEDIA_SHARED
Storage state if the media is present not mounted, and shared via USB
mass storage.
|
static String |
MEDIA_UNKNOWN
Unknown storage state, such as when a path isn't backed by known storage
media.
|
static String |
MEDIA_UNMOUNTABLE
Storage state if the media is present but cannot be mounted.
|
static String |
MEDIA_UNMOUNTED
Storage state if the media is present but not mounted.
|
static String[] |
STANDARD_DIRECTORIES
List of standard storage directories.
|
Constructor and Description |
---|
Environment() |
Modifier and Type | Method and Description |
---|---|
static File[] |
buildExternalStorageAndroidDataDirs()
Returns the path for android-specific data on the SD card.
|
static File[] |
buildExternalStorageAppCacheDirs(String packageName)
Generates the path to an application's cache.
|
static File[] |
buildExternalStorageAppDataDirs(String packageName)
Generates the raw path to an application's data
|
static File[] |
buildExternalStorageAppFilesDirs(String packageName)
Generates the path to an application's files.
|
static File[] |
buildExternalStorageAppMediaDirs(String packageName)
Generates the raw path to an application's media
|
static File[] |
buildExternalStorageAppObbDirs(String packageName)
Generates the raw path to an application's OBB files
|
static File |
buildPath(File base,
String... segments)
Append path segments to given base path, returning result.
|
static File[] |
buildPaths(File[] base,
String... segments)
Append path segments to each given base path, returning result.
|
static File |
getDataAppDirectory(String volumeUuid) |
static File |
getDataAppEphemeralDirectory(String volumeUuid) |
static File |
getDataDirectory()
Return the user data directory.
|
static File |
getDataDirectory(String volumeUuid) |
static File |
getDataMiscCeDirectory(int userId) |
static File |
getDataMiscDeDirectory(int userId) |
static File |
getDataMiscDirectory() |
static File |
getDataPreloadsAppsDirectory() |
static File |
getDataPreloadsDemoDirectory() |
static File |
getDataPreloadsDirectory()
Return preloads directory.
|
static File |
getDataPreloadsMediaDirectory() |
static File |
getDataProfilesDeForeignDexDirectory(int userId) |
static File |
getDataProfilesDePackageDirectory(int userId,
String packageName) |
static File |
getDataSystemCeDirectory()
Returns the base directory for per-user system directory, credential encrypted.
|
static File |
getDataSystemCeDirectory(int userId) |
static File |
getDataSystemDeDirectory()
Returns the base directory for per-user system directory, device encrypted.
|
static File |
getDataSystemDeDirectory(int userId) |
static File |
getDataSystemDirectory() |
static File |
getDataUserCeDirectory(String volumeUuid) |
static File |
getDataUserCeDirectory(String volumeUuid,
int userId) |
static File |
getDataUserCePackageDirectory(String volumeUuid,
int userId,
String packageName) |
static File |
getDataUserDeDirectory(String volumeUuid) |
static File |
getDataUserDeDirectory(String volumeUuid,
int userId) |
static File |
getDataUserDePackageDirectory(String volumeUuid,
int userId,
String packageName) |
static File |
getDownloadCacheDirectory()
Return the download/cache content directory.
|
static File |
getExpandDirectory() |
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 |
getLegacyExternalStorageDirectory() |
static File |
getLegacyExternalStorageObbDirectory() |
static File |
getOdmDirectory()
Return root directory of the "odm" partition holding ODM customizations,
if any.
|
static File |
getOemDirectory()
Return root directory of the "oem" partition holding OEM customizations,
if any.
|
static File |
getReferenceProfile(String packageName) |
static File |
getRootDirectory()
Return root of the "system" partition holding the core Android OS.
|
static File |
getStorageDirectory() |
static String |
getStorageState(File path)
Deprecated.
|
static File |
getUserConfigDirectory(int userId)
Deprecated.
This directory is valid and still exists, but callers should
strongly consider switching to
getDataMiscCeDirectory(int) which is protected with
user credentials or getDataMiscDeDirectory(int)
which supports fast user wipe. |
static File |
getUserSystemDirectory(int userId)
Deprecated.
This directory is valid and still exists, but callers should
strongly consider switching to
getDataSystemCeDirectory(int) which is protected
with user credentials or
getDataSystemDeDirectory(int) which supports fast
user wipe. |
static File |
getVendorDirectory()
Return root directory of the "vendor" partition that holds vendor-provided
software that should persist across simple reflashing of the "system" partition.
|
static void |
initForCurrentUser() |
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.
|
static boolean |
isStandardDirectory(String dir) |
static File |
maybeTranslateEmulatedPathToInternal(File path)
If the given path exists on emulated external storage, return the
translated backing path hosted on internal storage.
|
static void |
setUserRequired(boolean userRequired) |
public static final String DIR_ANDROID
@Deprecated public static final String DIRECTORY_ANDROID
public static String DIRECTORY_MUSIC
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.public static String DIRECTORY_PODCASTS
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.public static String DIRECTORY_RINGTONES
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 static String DIRECTORY_ALARMS
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.public static String DIRECTORY_NOTIFICATIONS
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.public static String DIRECTORY_PICTURES
public static String DIRECTORY_MOVIES
public static String DIRECTORY_DOWNLOADS
public static String DIRECTORY_DCIM
public static String DIRECTORY_DOCUMENTS
public static final String[] STANDARD_DIRECTORIES
Each of its values have its own constant:
public static final String MEDIA_UNKNOWN
public static final String MEDIA_REMOVED
public static final String MEDIA_UNMOUNTED
public static final String MEDIA_CHECKING
public static final String MEDIA_NOFS
public static final String MEDIA_MOUNTED
public static final String MEDIA_MOUNTED_READ_ONLY
public static final String MEDIA_SHARED
public static final String MEDIA_BAD_REMOVAL
public static final String MEDIA_UNMOUNTABLE
public static final String MEDIA_EJECTING
public static void initForCurrentUser()
public static File getRootDirectory()
public static File getStorageDirectory()
public static File getOemDirectory()
public static File getOdmDirectory()
public static File getVendorDirectory()
@Deprecated public static File getUserSystemDirectory(int userId)
getDataSystemCeDirectory(int)
which is protected
with user credentials or
getDataSystemDeDirectory(int)
which supports fast
user wipe.@Deprecated public static File getUserConfigDirectory(int userId)
getDataMiscCeDirectory(int)
which is protected with
user credentials or getDataMiscDeDirectory(int)
which supports fast user wipe.public static File getDataDirectory()
public static File getExpandDirectory()
public static File getDataSystemDirectory()
public static File getDataSystemDeDirectory()
public static File getDataSystemCeDirectory()
public static File getDataSystemCeDirectory(int userId)
public static File getDataSystemDeDirectory(int userId)
public static File getDataMiscDirectory()
public static File getDataMiscCeDirectory(int userId)
public static File getDataMiscDeDirectory(int userId)
public static File getDataProfilesDePackageDirectory(int userId, String packageName)
public static File getDataProfilesDeForeignDexDirectory(int userId)
public static File getDataUserCePackageDirectory(String volumeUuid, int userId, String packageName)
public static File getDataUserDePackageDirectory(String volumeUuid, int userId, String packageName)
public static File getDataPreloadsDirectory()
This directory may contain pre-loaded content such as
demo videos
and
APK files
.
public static File getExternalStorageDirectory()
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
Context.getExternalFilesDirs(String)
,
Context.getExternalCacheDirs()
, and
Context.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(java.lang.String)
.
Writing to this path requires the
android.Manifest.permission#WRITE_EXTERNAL_STORAGE
permission,
and starting in Build.VERSION_CODES.KITKAT
, read access requires the
android.Manifest.permission#READ_EXTERNAL_STORAGE
permission,
which is automatically granted if you hold the write permission.
Starting in Build.VERSION_CODES.KITKAT
, if your
application only needs to store internal data, consider using
Context.getExternalFilesDir(String)
,
Context.getExternalCacheDir()
, or
Context.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:
public static File getLegacyExternalStorageDirectory()
public static File getLegacyExternalStorageObbDirectory()
public static boolean isStandardDirectory(String dir)
public static File getExternalStoragePublicDirectory(String type)
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:
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
,
DIRECTORY_DCIM
, or DIRECTORY_DOCUMENTS
. May not be null.File.mkdirs()
.public static File[] buildExternalStorageAndroidDataDirs()
public static File[] buildExternalStorageAppDataDirs(String packageName)
public static File[] buildExternalStorageAppMediaDirs(String packageName)
public static File[] buildExternalStorageAppObbDirs(String packageName)
public static File[] buildExternalStorageAppFilesDirs(String packageName)
public static File[] buildExternalStorageAppCacheDirs(String packageName)
public static File getDownloadCacheDirectory()
public static String getExternalStorageState()
MEDIA_UNKNOWN
, MEDIA_REMOVED
,
MEDIA_UNMOUNTED
, MEDIA_CHECKING
,
MEDIA_NOFS
, MEDIA_MOUNTED
,
MEDIA_MOUNTED_READ_ONLY
, MEDIA_SHARED
,
MEDIA_BAD_REMOVAL
, or MEDIA_UNMOUNTABLE
.getExternalStorageDirectory()
@Deprecated public static String getStorageState(File path)
getExternalStorageState(File)
public static String getExternalStorageState(File 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
.public static boolean isExternalStorageRemovable()
public static boolean isExternalStorageRemovable(File path)
IllegalArgumentException
- if the path is not a valid storage
device.public static boolean isExternalStorageEmulated()
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
Context.getFilesDir()
, etc.
This returns true when emulated storage is backed by either internal storage or an adopted storage device.
public static boolean isExternalStorageEmulated(File path)
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
Context.getFilesDir()
, etc.
This returns true when emulated storage is backed by either internal storage or an adopted storage device.
IllegalArgumentException
- if the path is not a valid storage
device.public static void setUserRequired(boolean userRequired)
public static File[] buildPaths(File[] base, String... segments)
public static File buildPath(File base, String... segments)
public static File maybeTranslateEmulatedPathToInternal(File path)
Returns original path if given path doesn't meet these criteria. Callers
must hold android.Manifest.permission#WRITE_MEDIA_STORAGE
permission.