Environment
open class Environment
kotlin.Any | |
↳ | android.os.Environment |
Provides access to environment variables.
Summary
Constants | |
---|---|
static String |
Storage state if the media was removed before it was unmounted. |
static String |
Storage state if the media is present and being disk-checked. |
static String |
Storage state if the media is in the process of being ejected. |
static String |
Storage state if the media is present and mounted at its mount point with read/write access. |
static String |
Storage state if the media is present and mounted at its mount point with read-only access. |
static String |
Storage state if the media is present but is blank or is using an unsupported filesystem. |
static String |
Storage state if the media is not present. |
static String |
Storage state if the media is present not mounted, and shared via USB mass storage. |
static String |
Unknown storage state, such as when a path isn't backed by known storage media. |
static String |
Storage state if the media is present but cannot be mounted. |
static String |
Storage state if the media is present but not mounted. |
Public constructors | |
---|---|
Public methods | |
---|---|
open static File! |
Return the user data directory. |
open static File! |
Return the download/cache content directory. |
open static File! |
Return the primary shared/external storage directory. |
open static File! |
Get a top-level shared/external storage directory for placing files of a particular type. |
open static String! |
Returns the current state of the primary shared/external storage media. |
open static String! |
getExternalStorageState(path: File!) Returns the current state of the shared/external storage media at the given path. |
open static File |
Return root of the "system" partition holding the core Android OS. |
open static File |
Return root directory where all external storage devices will be mounted. |
open static String! |
getStorageState(path: File!) |
open static Boolean |
Returns whether the primary shared/external storage media is emulated. |
open static Boolean |
isExternalStorageEmulated(path: File) Returns whether the shared/external storage media at the given path is emulated. |
open static Boolean |
Returns whether the shared/external storage media is a legacy view that includes files not owned by the app. |
open static Boolean |
isExternalStorageLegacy(path: File) Returns whether the shared/external storage media is a legacy view that includes files not owned by the app. |
open static Boolean |
Returns whether the calling app has All Files Access on the primary shared/external storage media. |
open static Boolean |
isExternalStorageManager(path: File) Returns whether the calling app has All Files Access at the given |
open static Boolean |
Returns whether the primary shared/external storage media is physically removable. |
open static Boolean |
isExternalStorageRemovable(path: File) Returns whether the shared/external storage media at the given path is physically removable. |
Properties | |
---|---|
static String! |
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! |
Standard directory in which to place any audio files that should be in the list of audiobooks that the user can select (not as regular music). |
static String! |
The traditional location for pictures and videos when mounting the device as a camera. |
static String! |
Standard directory in which to place documents that have been created by the user. |
static String! |
Standard directory in which to place files that have been downloaded by the user. |
static String! |
Standard directory in which to place movies that are available to the user. |
static String! |
Standard directory in which to place any audio files that should be in the regular list of music for the user. |
static String! |
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! |
Standard directory in which to place pictures that are available to the user. |
static String! |
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 |
Standard directory in which to place any audio files that should be in the list of voice recordings recorded by voice recorder apps that the user can select (not as regular music). |
static String! |
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! |
Standard directory in which to place screenshots that have been taken by the user. |
Constants
MEDIA_BAD_REMOVAL
static val MEDIA_BAD_REMOVAL: String
Storage state if the media was removed before it was unmounted.
Value: "bad_removal"
See Also
MEDIA_CHECKING
static val MEDIA_CHECKING: String
Storage state if the media is present and being disk-checked.
Value: "checking"
See Also
MEDIA_EJECTING
static val MEDIA_EJECTING: String
Storage state if the media is in the process of being ejected.
Value: "ejecting"
See Also
MEDIA_MOUNTED
static val MEDIA_MOUNTED: String
Storage state if the media is present and mounted at its mount point with read/write access.
Value: "mounted"
See Also
MEDIA_MOUNTED_READ_ONLY
static val MEDIA_MOUNTED_READ_ONLY: String
Storage state if the media is present and mounted at its mount point with read-only access.
Value: "mounted_ro"
See Also
MEDIA_NOFS
static val MEDIA_NOFS: String
Storage state if the media is present but is blank or is using an unsupported filesystem.
Value: "nofs"
See Also
MEDIA_REMOVED
static val MEDIA_REMOVED: String
Storage state if the media is not present.
Value: "removed"
See Also
MEDIA_SHARED
static val MEDIA_SHARED: String
Storage state if the media is present not mounted, and shared via USB mass storage.
Value: "shared"
See Also
MEDIA_UNKNOWN
static val MEDIA_UNKNOWN: String
Unknown storage state, such as when a path isn't backed by known storage media.
Value: "unknown"
See Also
MEDIA_UNMOUNTABLE
static val MEDIA_UNMOUNTABLE: String
Storage state if the media is present but cannot be mounted. Typically this happens if the file system on the media is corrupted.
Value: "unmountable"
See Also
MEDIA_UNMOUNTED
static val MEDIA_UNMOUNTED: String
Storage state if the media is present but not mounted.
Value: "unmounted"
See Also
Public constructors
Environment
Environment()
Public methods
getDataDirectory
open static fun getDataDirectory(): File!
Return the user data directory.
getDownloadCacheDirectory
open static fun getDownloadCacheDirectory(): File!
Return the download/cache content directory.
getExternalStorageDirectory
open static fun getExternalStorageDirectory(): File!
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 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
.
Writing to this path requires the android.Manifest.permission#WRITE_EXTERNAL_STORAGE
permission, and starting in android.os.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 android.os.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:
Note that alternatives such as Context#getExternalFilesDir(String)
or MediaStore
offer better performance.
getExternalStoragePublicDirectory
open static fun getExternalStoragePublicDirectory(type: String!): File!
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:
Note that alternatives such as Context#getExternalFilesDir(String)
or MediaStore
offer better performance.
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. |
Return | |
---|---|
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
open static fun getExternalStorageState(): String!
Returns the current state of the primary shared/external storage media.
Return | |
---|---|
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
open static fun getExternalStorageState(path: File!): String!
Returns the current state of the shared/external storage media at the given path.
Return | |
---|---|
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
open static fun getRootDirectory(): File
Return root of the "system" partition holding the core Android OS. Always present and mounted read-only.
Return | |
---|---|
File |
This value cannot be null . |
getStorageDirectory
open static fun getStorageDirectory(): File
Return root directory where all external storage devices will be mounted. For example, getExternalStorageDirectory()
will appear under this location.
Return | |
---|---|
File |
This value cannot be null . |
getStorageState
open static fungetStorageState(path: File!): String!
Deprecated: use getExternalStorageState(java.io.File)
isExternalStorageEmulated
open static fun isExternalStorageEmulated(): Boolean
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 Context#getFilesDir()
, etc.
This returns true when emulated storage is backed by either internal storage or an adopted storage device.
isExternalStorageEmulated
open static fun isExternalStorageEmulated(path: File): Boolean
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 Context#getFilesDir()
, etc.
This returns true when emulated storage is backed by either internal storage or an adopted storage device.
Parameters | |
---|---|
path |
File: This value cannot be null . |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the path is not a valid storage device. |
isExternalStorageLegacy
open static fun isExternalStorageLegacy(): Boolean
Returns whether the shared/external storage media is a legacy view that includes files not owned by the app.
This value may be different from the value requested by requestLegacyExternalStorage
in the app's manifest, since an app may inherit its legacy state based on when it was first installed, target sdk and other factors.
Non-legacy apps can continue to discover and read media belonging to other apps via android.provider.MediaStore
.
isExternalStorageLegacy
open static fun isExternalStorageLegacy(path: File): Boolean
Returns whether the shared/external storage media is a legacy view that includes files not owned by the app.
This value may be different from the value requested by requestLegacyExternalStorage
in the app's manifest, since an app may inherit its legacy state based on when it was first installed, target sdk and other factors.
Non-legacy apps can continue to discover and read media belonging to other apps via android.provider.MediaStore
.
Parameters | |
---|---|
path |
File: This value cannot be null . |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the path is not a valid storage device. |
isExternalStorageManager
open static fun isExternalStorageManager(): Boolean
Returns whether the calling app has All Files Access on the primary shared/external storage media.
Declaring the permission android.Manifest.permission#MANAGE_EXTERNAL_STORAGE
isn't enough to gain the access.
To request access, use android.provider.Settings#ACTION_MANAGE_APP_ALL_FILES_ACCESS_PERMISSION
.
isExternalStorageManager
open static fun isExternalStorageManager(path: File): Boolean
Returns whether the calling app has All Files Access at the given path
Declaring the permission android.Manifest.permission#MANAGE_EXTERNAL_STORAGE
isn't enough to gain the access.
To request access, use android.provider.Settings#ACTION_MANAGE_APP_ALL_FILES_ACCESS_PERMISSION
.
Parameters | |
---|---|
path |
File: This value cannot be null . |
isExternalStorageRemovable
open static fun isExternalStorageRemovable(): Boolean
Returns whether the primary shared/external storage media is physically removable.
Return | |
---|---|
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
open static fun isExternalStorageRemovable(path: File): Boolean
Returns whether the shared/external storage media at the given path is physically removable.
Parameters | |
---|---|
path |
File: This value cannot be null . |
Return | |
---|---|
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. |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the path is not a valid storage device. |
Properties
DIRECTORY_ALARMS
static var DIRECTORY_ALARMS: String!
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_AUDIOBOOKS
, DIRECTORY_PODCASTS
, DIRECTORY_NOTIFICATIONS
, DIRECTORY_RINGTONES
, and DIRECTORY_RECORDINGS
as a series of directories to categorize a particular audio file as more than one type.
DIRECTORY_AUDIOBOOKS
static var DIRECTORY_AUDIOBOOKS: String!
Standard directory in which to place any audio files that should be in the list of audiobooks that the user can select (not as regular music). This may be combined with DIRECTORY_MUSIC
, DIRECTORY_PODCASTS
, DIRECTORY_NOTIFICATIONS
, DIRECTORY_ALARMS
, DIRECTORY_RINGTONES
, and DIRECTORY_RECORDINGS
as a series of directories to categorize a particular audio file as more than one type.
DIRECTORY_DCIM
static var DIRECTORY_DCIM: String!
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
static var DIRECTORY_DOCUMENTS: String!
Standard directory in which to place documents that have been created by the user.
DIRECTORY_DOWNLOADS
static var DIRECTORY_DOWNLOADS: String!
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
static var DIRECTORY_MOVIES: String!
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
static var DIRECTORY_MUSIC: String!
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_AUDIOBOOKS
, DIRECTORY_PODCASTS
, DIRECTORY_NOTIFICATIONS
, DIRECTORY_ALARMS
, DIRECTORY_RINGTONES
, and DIRECTORY_RECORDINGS
as a series of directories to categorize a particular audio file as more than one type.
DIRECTORY_NOTIFICATIONS
static var DIRECTORY_NOTIFICATIONS: String!
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_AUDIOBOOKS
, DIRECTORY_PODCASTS
, DIRECTORY_ALARMS
, DIRECTORY_RINGTONES
, and DIRECTORY_RECORDINGS
as a series of directories to categorize a particular audio file as more than one type.
DIRECTORY_PICTURES
static var DIRECTORY_PICTURES: String!
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
static var DIRECTORY_PODCASTS: String!
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_AUDIOBOOKS
, DIRECTORY_NOTIFICATIONS
, DIRECTORY_ALARMS
, DIRECTORY_RINGTONES
, and DIRECTORY_RECORDINGS
as a series of directories to categorize a particular audio file as more than one type.
DIRECTORY_RECORDINGS
static var DIRECTORY_RECORDINGS: String
Standard directory in which to place any audio files that should be in the list of voice recordings recorded by voice recorder apps that the user can select (not as regular music). This may be combined with DIRECTORY_MUSIC
, DIRECTORY_AUDIOBOOKS
, DIRECTORY_PODCASTS
, DIRECTORY_NOTIFICATIONS
, DIRECTORY_ALARMS
, and DIRECTORY_RINGTONES
as a series of directories to categorize a particular audio file as more than one type.
DIRECTORY_RINGTONES
static var DIRECTORY_RINGTONES: String!
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_AUDIOBOOKS
, DIRECTORY_PODCASTS
, DIRECTORY_NOTIFICATIONS
, DIRECTORY_ALARMS
, and DIRECTORY_RECORDINGS
as a series of directories to categorize a particular audio file as more than one type.
DIRECTORY_SCREENSHOTS
static var DIRECTORY_SCREENSHOTS: String!
Standard directory in which to place screenshots that have been taken by the user. Typically used as a secondary directory under DIRECTORY_PICTURES
.