Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am d56756fd: am 535726f6: am 0c15693e: Merge "Update docs to reflect adoptable behavior." into mnc-dr-dev

Browse Source 
* commit 'd56756fdee9fce3d08bea769710d7173bcbc263a':
  Update docs to reflect adoptable behavior.
This commit is contained in:
Jeff Sharkey
2015-10-16 16:38:29 +00:00
committed by Android Git Automerger
parent 704127b1a0 d56756fdee
commit de0b34ea14
2 changed files with 390 additions and 259 deletions
Download Patch File Download Diff File Expand all files Collapse all files

508
core/java/android/content/Context.java
View File

@@ -644,19 +644,17 @@ public abstract class Context {
/** /**
* Open a private file associated with this Context's application package * Open a private file associated with this Context's application package
* for writing. Creates the file if it doesn't already exist. * for writing. Creates the file if it doesn't already exist.
* * <p>
* <p>No permissions are required to invoke this method, since it uses internal * No additional permissions are required for the calling app to read or
* storage. * write the returned file.
* *
* @param name The name of the file to open; can not contain path * @param name The name of the file to open; can not contain path
* separators. * separators.
* @param mode Operating mode. Use 0 or {@link #MODE_PRIVATE} for the * @param mode Operating mode. Use 0 or {@link #MODE_PRIVATE} for the
* default operation, {@link #MODE_APPEND} to append to an existing file, * default operation, {@link #MODE_APPEND} to append to an
* {@link #MODE_WORLD_READABLE} and {@link #MODE_WORLD_WRITEABLE} to control * existing file, {@link #MODE_WORLD_READABLE} and
* permissions. * {@link #MODE_WORLD_WRITEABLE} to control permissions.
*
* @return The resulting {@link FileOutputStream}. * @return The resulting {@link FileOutputStream}.
*
* @see #MODE_APPEND * @see #MODE_APPEND
* @see #MODE_PRIVATE * @see #MODE_PRIVATE
* @see #MODE_WORLD_READABLE * @see #MODE_WORLD_READABLE
@@ -689,6 +687,9 @@ public abstract class Context {
/** /**
* Returns the absolute path on the filesystem where a file created with * Returns the absolute path on the filesystem where a file created with
* {@link #openFileOutput} is stored. * {@link #openFileOutput} is stored.
* <p>
* The returned path may change over time if the calling app is moved to an
* adopted storage device, so only relative paths should be persisted.
* *
* @param name The name of the file for which you would like to get * @param name The name of the file for which you would like to get
* its path. * its path.
@@ -702,14 +703,16 @@ public abstract class Context {
public abstract File getFileStreamPath(String name); public abstract File getFileStreamPath(String name);
/** /**
* Returns the absolute path to the directory on the filesystem where * Returns the absolute path to the directory on the filesystem where files
* files created with {@link #openFileOutput} are stored. * created with {@link #openFileOutput} are stored.
* * <p>
* <p>No permissions are required to read or write to the returned path, since this * The returned path may change over time if the calling app is moved to an
* path is internal storage. * adopted storage device, so only relative paths should be persisted.
* <p>
* No additional permissions are required for the calling app to read or
* write files under the returned path.
* *
* @return The path of the directory holding application files. * @return The path of the directory holding application files.
*
* @see #openFileOutput * @see #openFileOutput
* @see #getFileStreamPath * @see #getFileStreamPath
* @see #getDir * @see #getDir
@@ -722,13 +725,15 @@ public abstract class Context {
* directory will be excluded from automatic backup to remote storage. See * directory will be excluded from automatic backup to remote storage. See
* {@link android.app.backup.BackupAgent BackupAgent} for a full discussion * {@link android.app.backup.BackupAgent BackupAgent} for a full discussion
* of the automatic backup mechanism in Android. * of the automatic backup mechanism in Android.
* <p>
* The returned path may change over time if the calling app is moved to an
* adopted storage device, so only relative paths should be persisted.
* <p>
* No additional permissions are required for the calling app to read or
* write files under the returned path.
* *
* <p>No permissions are required to read or write to the returned path, since this * @return The path of the directory holding application files that will not
* path is internal storage. * be automatically backed up to remote storage.
*
* @return The path of the directory holding application files that will not be
* automatically backed up to remote storage.
*
* @see #openFileOutput * @see #openFileOutput
* @see #getFileStreamPath * @see #getFileStreamPath
* @see #getDir * @see #getDir
@@ -737,69 +742,75 @@ public abstract class Context {
public abstract File getNoBackupFilesDir(); public abstract File getNoBackupFilesDir();
/** /**
* Returns the absolute path to the directory on the primary external filesystem * Returns the absolute path to the directory on the primary shared/external
* (that is somewhere on {@link android.os.Environment#getExternalStorageDirectory() * storage device where the application can place persistent files it owns.
* Environment.getExternalStorageDirectory()}) where the application can * These files are internal to the applications, and not typically visible
* place persistent files it owns. These files are internal to the * to the user as media.
* applications, and not typically visible to the user as media. * <p>
* * This is like {@link #getFilesDir()} in that these files will be deleted
* <p>This is like {@link #getFilesDir()} in that these * when the application is uninstalled, however there are some important
* files will be deleted when the application is uninstalled, however there * differences:
* are some important differences:
*
* <ul> * <ul>
* <li>External files are not always available: they will disappear if the * <li>Shared storage may not always be available, since removable media can
* user mounts the external storage on a computer or removes it. See the * be ejected by the user. Media state can be checked using
* APIs on {@link android.os.Environment} for information in the storage state. * {@link Environment#getExternalStorageState(File)}.
* <li>There is no security enforced with these files. For example, any application * <li>There is no security enforced with these files. For example, any
* holding {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to * application holding
* {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to
* these files. * these files.
* </ul> * </ul>
* * <p>
* <p>Starting in {@link android.os.Build.VERSION_CODES#KITKAT}, no permissions * If a shared storage device is emulated (as determined by
* {@link Environment#isExternalStorageEmulated(File)}), it's contents are
* backed by a private user data partition, which means there is little
* benefit to storing data here instead of the private directories returned
* by {@link #getFilesDir()}, etc.
* <p>
* Starting in {@link android.os.Build.VERSION_CODES#KITKAT}, no permissions
* are required to read or write to the returned path; it's always * are required to read or write to the returned path; it's always
* accessible to the calling app. This only applies to paths generated for * accessible to the calling app. This only applies to paths generated for
* package name of the calling application. To access paths belonging * package name of the calling application. To access paths belonging to
* to other packages, {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} * other packages,
* and/or {@link android.Manifest.permission#READ_EXTERNAL_STORAGE} are required. * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} and/or
* * {@link android.Manifest.permission#READ_EXTERNAL_STORAGE} are required.
* <p>On devices with multiple users (as described by {@link UserManager}), * <p>
* each user has their own isolated external storage. Applications only * On devices with multiple users (as described by {@link UserManager}),
* have access to the external storage for the user they're running as.</p> * each user has their own isolated shared storage. Applications only have
* * access to the shared storage for the user they're running as.
* <p>Here is an example of typical code to manipulate a file in * <p>
* an application's private storage:</p> * The returned path may change over time if different shared storage media
* * is inserted, so only relative paths should be persisted.
* <p>
* Here is an example of typical code to manipulate a file in an
* application's shared storage:
* </p>
* {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java * {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java
* private_file} * private_file}
* * <p>
* <p>If you supply a non-null <var>type</var> to this function, the returned * If you supply a non-null <var>type</var> to this function, the returned
* file will be a path to a sub-directory of the given type. Though these files * file will be a path to a sub-directory of the given type. Though these
* are not automatically scanned by the media scanner, you can explicitly * files are not automatically scanned by the media scanner, you can
* add them to the media database with * explicitly add them to the media database with
* {@link android.media.MediaScannerConnection#scanFile(Context, String[], String[], * {@link android.media.MediaScannerConnection#scanFile(Context, String[], String[], android.media.MediaScannerConnection.OnScanCompletedListener)
* android.media.MediaScannerConnection.OnScanCompletedListener) * MediaScannerConnection.scanFile}. Note that this is not the same as
* MediaScannerConnection.scanFile}.
* Note that this is not the same as
* {@link android.os.Environment#getExternalStoragePublicDirectory * {@link android.os.Environment#getExternalStoragePublicDirectory
* Environment.getExternalStoragePublicDirectory()}, which provides * Environment.getExternalStoragePublicDirectory()}, which provides
* directories of media shared by all applications. The * directories of media shared by all applications. The directories returned
* directories returned here are * here are owned by the application, and their contents will be removed
* owned by the application, and their contents will be removed when the * when the application is uninstalled. Unlike
* application is uninstalled. Unlike
* {@link android.os.Environment#getExternalStoragePublicDirectory * {@link android.os.Environment#getExternalStoragePublicDirectory
* Environment.getExternalStoragePublicDirectory()}, the directory * Environment.getExternalStoragePublicDirectory()}, the directory returned
* returned here will be automatically created for you. * here will be automatically created for you.
* * <p>
* <p>Here is an example of typical code to manipulate a picture in * Here is an example of typical code to manipulate a picture in an
* an application's private storage and add it to the media database:</p> * application's shared storage and add it to the media database:
* * </p>
* {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java * {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java
* private_picture} * private_picture}
* *
* @param type The type of files directory to return. May be null for * @param type The type of files directory to return. May be {@code null}
* the root of the files directory or one of * for the root of the files directory or one of the following
* the following Environment constants for a subdirectory: * constants for a subdirectory:
* {@link android.os.Environment#DIRECTORY_MUSIC}, * {@link android.os.Environment#DIRECTORY_MUSIC},
* {@link android.os.Environment#DIRECTORY_PODCASTS}, * {@link android.os.Environment#DIRECTORY_PODCASTS},
* {@link android.os.Environment#DIRECTORY_RINGTONES}, * {@link android.os.Environment#DIRECTORY_RINGTONES},
@@ -807,130 +818,180 @@ public abstract class Context {
* {@link android.os.Environment#DIRECTORY_NOTIFICATIONS}, * {@link android.os.Environment#DIRECTORY_NOTIFICATIONS},
* {@link android.os.Environment#DIRECTORY_PICTURES}, or * {@link android.os.Environment#DIRECTORY_PICTURES}, or
* {@link android.os.Environment#DIRECTORY_MOVIES}. * {@link android.os.Environment#DIRECTORY_MOVIES}.
* * @return the absolute path to application-specific directory. May return
* @return The path of the directory holding application files * {@code null} if shared storage is not currently available.
* on external storage. Returns null if external storage is not currently
* mounted so it could not ensure the path exists; you will need to call
* this method again when it is available.
*
* @see #getFilesDir * @see #getFilesDir
* @see android.os.Environment#getExternalStoragePublicDirectory * @see #getExternalFilesDirs(String)
* @see Environment#getExternalStorageState(File)
* @see Environment#isExternalStorageEmulated(File)
* @see Environment#isExternalStorageRemovable(File)
*/ */
@Nullable @Nullable
public abstract File getExternalFilesDir(@Nullable String type); public abstract File getExternalFilesDir(@Nullable String type);
/** /**
* Returns absolute paths to application-specific directories on all * Returns absolute paths to application-specific directories on all
* external storage devices where the application can place persistent files * shared/external storage devices where the application can place
* it owns. These files are internal to the application, and not typically * persistent files it owns. These files are internal to the application,
* visible to the user as media. * and not typically visible to the user as media.
* <p> * <p>
* This is like {@link #getFilesDir()} in that these files will be deleted when * This is like {@link #getFilesDir()} in that these files will be deleted
* the application is uninstalled, however there are some important differences: * when the application is uninstalled, however there are some important
* differences:
* <ul> * <ul>
* <li>External files are not always available: they will disappear if the * <li>Shared storage may not always be available, since removable media can
* user mounts the external storage on a computer or removes it. * be ejected by the user. Media state can be checked using
* <li>There is no security enforced with these files. * {@link Environment#getExternalStorageState(File)}.
* <li>There is no security enforced with these files. For example, any
* application holding
* {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to
* these files.
* </ul> * </ul>
* <p> * <p>
* External storage devices returned here are considered a permanent part of * If a shared storage device is emulated (as determined by
* the device, including both emulated external storage and physical media * {@link Environment#isExternalStorageEmulated(File)}), it's contents are
* slots, such as SD cards in a battery compartment. The returned paths do * backed by a private user data partition, which means there is little
* not include transient devices, such as USB flash drives. * benefit to storing data here instead of the private directories returned
* by {@link #getFilesDir()}, etc.
* <p>
* Shared storage devices returned here are considered a stable part of the
* device, including physical media slots under a protective cover. The
* returned paths do not include transient devices, such as USB flash drives
* connected to handheld devices.
* <p> * <p>
* An application may store data on any or all of the returned devices. For * An application may store data on any or all of the returned devices. For
* example, an app may choose to store large files on the device with the * example, an app may choose to store large files on the device with the
* most available space, as measured by {@link StatFs}. * most available space, as measured by {@link StatFs}.
* <p> * <p>
* No permissions are required to read or write to the returned paths; they * No additional permissions are required for the calling app to read or
* are always accessible to the calling app. Write access outside of these * write files under the returned path. Write access outside of these paths
* paths on secondary external storage devices is not available. * on secondary external storage devices is not available.
* <p> * <p>
* The first path returned is the same as {@link #getExternalFilesDir(String)}. * The returned path may change over time if different shared storage media
* Returned paths may be {@code null} if a storage device is unavailable. * is inserted, so only relative paths should be persisted.
* *
* @param type The type of files directory to return. May be {@code null}
* for the root of the files directory or one of the following
* constants for a subdirectory:
* {@link android.os.Environment#DIRECTORY_MUSIC},
* {@link android.os.Environment#DIRECTORY_PODCASTS},
* {@link android.os.Environment#DIRECTORY_RINGTONES},
* {@link android.os.Environment#DIRECTORY_ALARMS},
* {@link android.os.Environment#DIRECTORY_NOTIFICATIONS},
* {@link android.os.Environment#DIRECTORY_PICTURES}, or
* {@link android.os.Environment#DIRECTORY_MOVIES}.
* @return the absolute paths to application-specific directories. Some
* individual paths may be {@code null} if that shared storage is
* not currently available. The first path returned is the same as
* {@link #getExternalFilesDir(String)}.
* @see #getExternalFilesDir(String) * @see #getExternalFilesDir(String)
* @see Environment#getExternalStorageState(File) * @see Environment#getExternalStorageState(File)
* @see Environment#isExternalStorageEmulated(File)
* @see Environment#isExternalStorageRemovable(File)
*/ */
public abstract File[] getExternalFilesDirs(String type); public abstract File[] getExternalFilesDirs(String type);
/** /**
* Return the primary external storage directory where this application's OBB * Return the primary shared/external storage directory where this
* files (if there are any) can be found. Note if the application does not have * application's OBB files (if there are any) can be found. Note if the
* any OBB files, this directory may not exist. * application does not have any OBB files, this directory may not exist.
* <p> * <p>
* This is like {@link #getFilesDir()} in that these files will be deleted when * This is like {@link #getFilesDir()} in that these files will be deleted
* the application is uninstalled, however there are some important differences: * when the application is uninstalled, however there are some important
* differences:
* <ul> * <ul>
* <li>External files are not always available: they will disappear if the * <li>Shared storage may not always be available, since removable media can
* user mounts the external storage on a computer or removes it. * be ejected by the user. Media state can be checked using
* <li>There is no security enforced with these files. For example, any application * {@link Environment#getExternalStorageState(File)}.
* holding {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to * <li>There is no security enforced with these files. For example, any
* application holding
* {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to
* these files. * these files.
* </ul> * </ul>
* <p> * <p>
* Starting in {@link android.os.Build.VERSION_CODES#KITKAT}, no permissions * Starting in {@link android.os.Build.VERSION_CODES#KITKAT}, no permissions
* are required to read or write to the returned path; it's always * are required to read or write to the returned path; it's always
* accessible to the calling app. This only applies to paths generated for * accessible to the calling app. This only applies to paths generated for
* package name of the calling application. To access paths belonging * package name of the calling application. To access paths belonging to
* to other packages, {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} * other packages,
* and/or {@link android.Manifest.permission#READ_EXTERNAL_STORAGE} are required. * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} and/or
* {@link android.Manifest.permission#READ_EXTERNAL_STORAGE} are required.
* <p> * <p>
* On devices with multiple users (as described by {@link UserManager}), * On devices with multiple users (as described by {@link UserManager}),
* multiple users may share the same OBB storage location. Applications * multiple users may share the same OBB storage location. Applications
* should ensure that multiple instances running under different users don't * should ensure that multiple instances running under different users don't
* interfere with each other. * interfere with each other.
*
* @return the absolute path to application-specific directory. May return
* {@code null} if shared storage is not currently available.
* @see #getObbDirs()
* @see Environment#getExternalStorageState(File)
* @see Environment#isExternalStorageEmulated(File)
* @see Environment#isExternalStorageRemovable(File)
*/ */
public abstract File getObbDir(); public abstract File getObbDir();
/** /**
* Returns absolute paths to application-specific directories on all * Returns absolute paths to application-specific directories on all
* external storage devices where the application's OBB files (if there are * shared/external storage devices where the application's OBB files (if
* any) can be found. Note if the application does not have any OBB files, * there are any) can be found. Note if the application does not have any
* these directories may not exist. * OBB files, these directories may not exist.
* <p> * <p>
* This is like {@link #getFilesDir()} in that these files will be deleted when * This is like {@link #getFilesDir()} in that these files will be deleted
* the application is uninstalled, however there are some important differences: * when the application is uninstalled, however there are some important
* differences:
* <ul> * <ul>
* <li>External files are not always available: they will disappear if the * <li>Shared storage may not always be available, since removable media can
* user mounts the external storage on a computer or removes it. * be ejected by the user. Media state can be checked using
* <li>There is no security enforced with these files. * {@link Environment#getExternalStorageState(File)}.
* <li>There is no security enforced with these files. For example, any
* application holding
* {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to
* these files.
* </ul> * </ul>
* <p> * <p>
* External storage devices returned here are considered a permanent part of * Shared storage devices returned here are considered a stable part of the
* the device, including both emulated external storage and physical media * device, including physical media slots under a protective cover. The
* slots, such as SD cards in a battery compartment. The returned paths do * returned paths do not include transient devices, such as USB flash drives
* not include transient devices, such as USB flash drives. * connected to handheld devices.
* <p> * <p>
* An application may store data on any or all of the returned devices. For * An application may store data on any or all of the returned devices. For
* example, an app may choose to store large files on the device with the * example, an app may choose to store large files on the device with the
* most available space, as measured by {@link StatFs}. * most available space, as measured by {@link StatFs}.
* <p> * <p>
* No permissions are required to read or write to the returned paths; they * No additional permissions are required for the calling app to read or
* are always accessible to the calling app. Write access outside of these * write files under the returned path. Write access outside of these paths
* paths on secondary external storage devices is not available. * on secondary external storage devices is not available.
* <p>
* The first path returned is the same as {@link #getObbDir()}.
* Returned paths may be {@code null} if a storage device is unavailable.
* *
* @return the absolute paths to application-specific directories. Some
* individual paths may be {@code null} if that shared storage is
* not currently available. The first path returned is the same as
* {@link #getObbDir()}
* @see #getObbDir() * @see #getObbDir()
* @see Environment#getExternalStorageState(File) * @see Environment#getExternalStorageState(File)
* @see Environment#isExternalStorageEmulated(File)
* @see Environment#isExternalStorageRemovable(File)
*/ */
public abstract File[] getObbDirs(); public abstract File[] getObbDirs();
/** /**
* Returns the absolute path to the application specific cache directory * Returns the absolute path to the application specific cache directory on
* on the filesystem. These files will be ones that get deleted first when the * the filesystem. These files will be ones that get deleted first when the
* device runs low on storage. * device runs low on storage. There is no guarantee when these files will
* There is no guarantee when these files will be deleted. * be deleted.
* * <p>
* <strong>Note: you should not <em>rely</em> on the system deleting these * <strong>Note: you should not <em>rely</em> on the system deleting these
* files for you; you should always have a reasonable maximum, such as 1 MB, * files for you; you should always have a reasonable maximum, such as 1 MB,
* for the amount of space you consume with cache files, and prune those * for the amount of space you consume with cache files, and prune those
* files when exceeding that space.</strong> * files when exceeding that space.</strong>
* <p>
* The returned path may change over time if the calling app is moved to an
* adopted storage device, so only relative paths should be persisted.
* <p>
* Apps require no extra permissions to read or write to the returned path,
* since this path lives in their private storage.
* *
* @return The path of the directory holding application cache files. * @return The path of the directory holding application cache files.
*
* @see #openFileOutput * @see #openFileOutput
* @see #getFileStreamPath * @see #getFileStreamPath
* @see #getDir * @see #getDir
@@ -946,6 +1007,9 @@ public abstract class Context {
* This location is optimal for storing compiled or optimized code generated * This location is optimal for storing compiled or optimized code generated
* by your application at runtime. * by your application at runtime.
* <p> * <p>
* The returned path may change over time if the calling app is moved to an
* adopted storage device, so only relative paths should be persisted.
* <p>
* Apps require no extra permissions to read or write to the returned path, * Apps require no extra permissions to read or write to the returned path,
* since this path lives in their private storage. * since this path lives in their private storage.
* *
@@ -954,120 +1018,161 @@ public abstract class Context {
public abstract File getCodeCacheDir(); public abstract File getCodeCacheDir();
/** /**
* Returns the absolute path to the directory on the primary external filesystem * Returns absolute path to application-specific directory on the primary
* (that is somewhere on {@link android.os.Environment#getExternalStorageDirectory() * shared/external storage device where the application can place cache
* Environment.getExternalStorageDirectory()} where the application can * files it owns. These files are internal to the application, and not
* place cache files it owns. These files are internal to the application, and * typically visible to the user as media.
* not typically visible to the user as media. * <p>
* * This is like {@link #getCacheDir()} in that these files will be deleted
* <p>This is like {@link #getCacheDir()} in that these * when the application is uninstalled, however there are some important
* files will be deleted when the application is uninstalled, however there * differences:
* are some important differences:
*
* <ul> * <ul>
* <li>The platform does not always monitor the space available in external * <li>The platform does not always monitor the space available in shared
* storage, and thus may not automatically delete these files. Currently * storage, and thus may not automatically delete these files. Apps should
* the only time files here will be deleted by the platform is when running * always manage the maximum space used in this location. Currently the only
* on {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1} or later and * time files here will be deleted by the platform is when running on
* {@link android.os.Environment#isExternalStorageEmulated() * {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1} or later and
* Environment.isExternalStorageEmulated()} returns true. Note that you should * {@link Environment#isExternalStorageEmulated(File)} returns true.
* be managing the maximum space you will use for these anyway, just like * <li>Shared storage may not always be available, since removable media can
* with {@link #getCacheDir()}. * be ejected by the user. Media state can be checked using
* <li>External files are not always available: they will disappear if the * {@link Environment#getExternalStorageState(File)}.
* user mounts the external storage on a computer or removes it. See the * <li>There is no security enforced with these files. For example, any
* APIs on {@link android.os.Environment} for information in the storage state. * application holding
* <li>There is no security enforced with these files. For example, any application * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to
* holding {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to
* these files. * these files.
* </ul> * </ul>
* * <p>
* <p>Starting in {@link android.os.Build.VERSION_CODES#KITKAT}, no permissions * If a shared storage device is emulated (as determined by
* {@link Environment#isExternalStorageEmulated(File)}), it's contents are
* backed by a private user data partition, which means there is little
* benefit to storing data here instead of the private directory returned by
* {@link #getCacheDir()}.
* <p>
* Starting in {@link android.os.Build.VERSION_CODES#KITKAT}, no permissions
* are required to read or write to the returned path; it's always * are required to read or write to the returned path; it's always
* accessible to the calling app. This only applies to paths generated for * accessible to the calling app. This only applies to paths generated for
* package name of the calling application. To access paths belonging * package name of the calling application. To access paths belonging to
* to other packages, {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} * other packages,
* and/or {@link android.Manifest.permission#READ_EXTERNAL_STORAGE} are required. * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} and/or
* * {@link android.Manifest.permission#READ_EXTERNAL_STORAGE} are required.
* <p>On devices with multiple users (as described by {@link UserManager}), * <p>
* each user has their own isolated external storage. Applications only * On devices with multiple users (as described by {@link UserManager}),
* have access to the external storage for the user they're running as.</p> * each user has their own isolated shared storage. Applications only have
* * access to the shared storage for the user they're running as.
* @return The path of the directory holding application cache files * <p>
* on external storage. Returns null if external storage is not currently * The returned path may change over time if different shared storage media
* mounted so it could not ensure the path exists; you will need to call * is inserted, so only relative paths should be persisted.
* this method again when it is available.
* *
* @return the absolute path to application-specific directory. May return
* {@code null} if shared storage is not currently available.
* @see #getCacheDir * @see #getCacheDir
* @see #getExternalCacheDirs()
* @see Environment#getExternalStorageState(File)
* @see Environment#isExternalStorageEmulated(File)
* @see Environment#isExternalStorageRemovable(File)
*/ */
@Nullable @Nullable
public abstract File getExternalCacheDir(); public abstract File getExternalCacheDir();
/** /**
* Returns absolute paths to application-specific directories on all * Returns absolute paths to application-specific directories on all
* external storage devices where the application can place cache files it * shared/external storage devices where the application can place cache
* owns. These files are internal to the application, and not typically * files it owns. These files are internal to the application, and not
* visible to the user as media. * typically visible to the user as media.
* <p> * <p>
* This is like {@link #getCacheDir()} in that these files will be deleted when * This is like {@link #getCacheDir()} in that these files will be deleted
* the application is uninstalled, however there are some important differences: * when the application is uninstalled, however there are some important
* differences:
* <ul> * <ul>
* <li>External files are not always available: they will disappear if the * <li>The platform does not always monitor the space available in shared
* user mounts the external storage on a computer or removes it. * storage, and thus may not automatically delete these files. Apps should
* <li>There is no security enforced with these files. * always manage the maximum space used in this location. Currently the only
* time files here will be deleted by the platform is when running on
* {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1} or later and
* {@link Environment#isExternalStorageEmulated(File)} returns true.
* <li>Shared storage may not always be available, since removable media can
* be ejected by the user. Media state can be checked using
* {@link Environment#getExternalStorageState(File)}.
* <li>There is no security enforced with these files. For example, any
* application holding
* {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to
* these files.
* </ul> * </ul>
* <p> * <p>
* External storage devices returned here are considered a permanent part of * If a shared storage device is emulated (as determined by
* the device, including both emulated external storage and physical media * {@link Environment#isExternalStorageEmulated(File)}), it's contents are
* slots, such as SD cards in a battery compartment. The returned paths do * backed by a private user data partition, which means there is little
* not include transient devices, such as USB flash drives. * benefit to storing data here instead of the private directory returned by
* {@link #getCacheDir()}.
* <p>
* Shared storage devices returned here are considered a stable part of the
* device, including physical media slots under a protective cover. The
* returned paths do not include transient devices, such as USB flash drives
* connected to handheld devices.
* <p> * <p>
* An application may store data on any or all of the returned devices. For * An application may store data on any or all of the returned devices. For
* example, an app may choose to store large files on the device with the * example, an app may choose to store large files on the device with the
* most available space, as measured by {@link StatFs}. * most available space, as measured by {@link StatFs}.
* <p> * <p>
* No permissions are required to read or write to the returned paths; they * No additional permissions are required for the calling app to read or
* are always accessible to the calling app. Write access outside of these * write files under the returned path. Write access outside of these paths
* paths on secondary external storage devices is not available. * on secondary external storage devices is not available.
* <p> * <p>
* The first path returned is the same as {@link #getExternalCacheDir()}. * The returned paths may change over time if different shared storage media
* Returned paths may be {@code null} if a storage device is unavailable. * is inserted, so only relative paths should be persisted.
* *
* @return the absolute paths to application-specific directories. Some
* individual paths may be {@code null} if that shared storage is
* not currently available. The first path returned is the same as
* {@link #getExternalCacheDir()}.
* @see #getExternalCacheDir() * @see #getExternalCacheDir()
* @see Environment#getExternalStorageState(File) * @see Environment#getExternalStorageState(File)
* @see Environment#isExternalStorageEmulated(File)
* @see Environment#isExternalStorageRemovable(File)
*/ */
public abstract File[] getExternalCacheDirs(); public abstract File[] getExternalCacheDirs();
/** /**
* Returns absolute paths to application-specific directories on all * Returns absolute paths to application-specific directories on all
* external storage devices where the application can place media files. * shared/external storage devices where the application can place media
* These files are scanned and made available to other apps through * files. These files are scanned and made available to other apps through
* {@link MediaStore}. * {@link MediaStore}.
* <p> * <p>
* This is like {@link #getExternalFilesDirs} in that these files will be * This is like {@link #getExternalFilesDirs} in that these files will be
* deleted when the application is uninstalled, however there are some * deleted when the application is uninstalled, however there are some
* important differences: * important differences:
* <ul> * <ul>
* <li>External files are not always available: they will disappear if the * <li>Shared storage may not always be available, since removable media can
* user mounts the external storage on a computer or removes it. * be ejected by the user. Media state can be checked using
* <li>There is no security enforced with these files. * {@link Environment#getExternalStorageState(File)}.
* <li>There is no security enforced with these files. For example, any
* application holding
* {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to
* these files.
* </ul> * </ul>
* <p> * <p>
* External storage devices returned here are considered a permanent part of * Shared storage devices returned here are considered a stable part of the
* the device, including both emulated external storage and physical media * device, including physical media slots under a protective cover. The
* slots, such as SD cards in a battery compartment. The returned paths do * returned paths do not include transient devices, such as USB flash drives
* not include transient devices, such as USB flash drives. * connected to handheld devices.
* <p> * <p>
* An application may store data on any or all of the returned devices. For * An application may store data on any or all of the returned devices. For
* example, an app may choose to store large files on the device with the * example, an app may choose to store large files on the device with the
* most available space, as measured by {@link StatFs}. * most available space, as measured by {@link StatFs}.
* <p> * <p>
* No permissions are required to read or write to the returned paths; they * No additional permissions are required for the calling app to read or
* are always accessible to the calling app. Write access outside of these * write files under the returned path. Write access outside of these paths
* paths on secondary external storage devices is not available. * on secondary external storage devices is not available.
* <p> * <p>
* Returned paths may be {@code null} if a storage device is unavailable. * The returned paths may change over time if different shared storage media
* is inserted, so only relative paths should be persisted.
* *
* @return the absolute paths to application-specific directories. Some
* individual paths may be {@code null} if that shared storage is
* not currently available.
* @see Environment#getExternalStorageState(File) * @see Environment#getExternalStorageState(File)
* @see Environment#isExternalStorageEmulated(File)
* @see Environment#isExternalStorageRemovable(File)
*/ */
public abstract File[] getExternalMediaDirs(); public abstract File[] getExternalMediaDirs();
@@ -1090,6 +1195,12 @@ public abstract class Context {
* created through a File object will only be accessible by your own * created through a File object will only be accessible by your own
* application; you can only set the mode of the entire directory, not * application; you can only set the mode of the entire directory, not
* of individual files. * of individual files.
* <p>
* The returned path may change over time if the calling app is moved to an
* adopted storage device, so only relative paths should be persisted.
* <p>
* Apps require no extra permissions to read or write to the returned path,
* since this path lives in their private storage.
* *
* @param name Name of the directory to retrieve. This is a directory * @param name Name of the directory to retrieve. This is a directory
* that is created as part of your application data. * that is created as part of your application data.
@@ -1173,6 +1284,9 @@ public abstract class Context {
/** /**
* Returns the absolute path on the filesystem where a database created with * Returns the absolute path on the filesystem where a database created with
* {@link #openOrCreateDatabase} is stored. * {@link #openOrCreateDatabase} is stored.
* <p>
* The returned path may change over time if the calling app is moved to an
* adopted storage device, so only relative paths should be persisted.
* *
* @param name The name of the database for which you would like to get * @param name The name of the database for which you would like to get
* its path. * its path.

93
core/java/android/os/Environment.java
View File

@@ -276,8 +276,8 @@ public class Environment {
} }
/** /**
* Return the primary external storage directory. This directory may not * Return the primary shared/external storage directory. This directory may
* currently be accessible if it has been mounted by the user on their * 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 * computer, has been removed from the device, or some other problem has
* happened. You can determine its current state with * happened. You can determine its current state with
* {@link #getExternalStorageState()}. * {@link #getExternalStorageState()}.
@@ -291,12 +291,15 @@ public class Environment {
* filesystem on a computer.</em> * filesystem on a computer.</em>
* <p> * <p>
* On devices with multiple users (as described by {@link UserManager}), * On devices with multiple users (as described by {@link UserManager}),
* each user has their own isolated external storage. Applications only have * each user has their own isolated shared storage. Applications only have
* access to the external storage for the user they're running as. * access to the shared storage for the user they're running as.
* <p> * <p>
* In devices with multiple "external" storage directories, this directory * In devices with multiple shared/external storage directories, this
* represents the "primary" external storage that the user will interact * directory represents the primary storage that the user will interact
* with. Access to secondary storage is available through * with. Access to secondary storage is available through
* {@link Context#getExternalFilesDirs(String)},
* {@link Context#getExternalCacheDirs()}, and
* {@link Context#getExternalMediaDirs()}.
* <p> * <p>
* Applications should not directly use this top-level directory, in order * 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 avoid polluting the user's root namespace. Any files that are private
@@ -315,8 +318,9 @@ public class Environment {
* <p> * <p>
* Starting in {@link android.os.Build.VERSION_CODES#KITKAT}, if your * Starting in {@link android.os.Build.VERSION_CODES#KITKAT}, if your
* application only needs to store internal data, consider using * application only needs to store internal data, consider using
* {@link Context#getExternalFilesDir(String)} or * {@link Context#getExternalFilesDir(String)},
* {@link Context#getExternalCacheDir()}, which require no permissions to * {@link Context#getExternalCacheDir()}, or
* {@link Context#getExternalMediaDirs()}, which require no permissions to
* read or write. * read or write.
* <p> * <p>
* This path may change between platform versions, so applications should * This path may change between platform versions, so applications should
@@ -325,8 +329,7 @@ public class Environment {
* Here is an example of typical code to monitor the state of external * Here is an example of typical code to monitor the state of external
* storage: * storage:
* <p> * <p>
* {@sample * {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java
* development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java
* monitor_storage} * monitor_storage}
* *
* @see #getExternalStorageState() * @see #getExternalStorageState()
@@ -446,19 +449,20 @@ public class Environment {
public static String DIRECTORY_DOCUMENTS = "Documents"; public static String DIRECTORY_DOCUMENTS = "Documents";
/** /**
* Get a top-level public external storage directory for placing files of * Get a top-level shared/external storage directory for placing files of a
* a particular type. This is where the user will typically place and * particular type. This is where the user will typically place and manage
* manage their own files, so you should be careful about what you put here * their own files, so you should be careful about what you put here to
* to ensure you don't erase their files or get in the way of their own * ensure you don't erase their files or get in the way of their own
* organization. * organization.
* * <p>
* <p>On devices with multiple users (as described by {@link UserManager}), * On devices with multiple users (as described by {@link UserManager}),
* each user has their own isolated external storage. Applications only * each user has their own isolated shared storage. Applications only have
* have access to the external storage for the user they're running as.</p> * access to the shared storage for the user they're running as.
* * </p>
* <p>Here is an example of typical code to manipulate a picture on * <p>
* the public external storage:</p> * Here is an example of typical code to manipulate a picture on the public
* * shared storage:
* </p>
* {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java * {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java
* public_picture} * public_picture}
* *
@@ -468,10 +472,9 @@ public class Environment {
* {@link #DIRECTORY_NOTIFICATIONS}, {@link #DIRECTORY_PICTURES}, * {@link #DIRECTORY_NOTIFICATIONS}, {@link #DIRECTORY_PICTURES},
* {@link #DIRECTORY_MOVIES}, {@link #DIRECTORY_DOWNLOADS}, or * {@link #DIRECTORY_MOVIES}, {@link #DIRECTORY_DOWNLOADS}, or
* {@link #DIRECTORY_DCIM}. May not be null. * {@link #DIRECTORY_DCIM}. May not be null.
* * @return Returns the File path for the directory. Note that this directory
* @return Returns the File path for the directory. Note that this * may not yet exist, so you must make sure it exists before using
* directory may not yet exist, so you must make sure it exists before * it such as with {@link File#mkdirs File.mkdirs()}.
* using it such as with {@link File#mkdirs File.mkdirs()}.
*/ */
public static File getExternalStoragePublicDirectory(String type) { public static File getExternalStoragePublicDirectory(String type) {
throwIfUserRequired(); throwIfUserRequired();
@@ -623,7 +626,7 @@ public class Environment {
public static final String MEDIA_EJECTING = "ejecting"; public static final String MEDIA_EJECTING = "ejecting";
/** /**
* Returns the current state of the primary "external" storage device. * Returns the current state of the primary shared/external storage media.
* *
* @see #getExternalStorageDirectory() * @see #getExternalStorageDirectory()
* @return one of {@link #MEDIA_UNKNOWN}, {@link #MEDIA_REMOVED}, * @return one of {@link #MEDIA_UNKNOWN}, {@link #MEDIA_REMOVED},
@@ -646,8 +649,8 @@ public class Environment {
} }
/** /**
* Returns the current state of the storage device that provides the given * Returns the current state of the shared/external storage media at the
* path. * given path.
* *
* @return one of {@link #MEDIA_UNKNOWN}, {@link #MEDIA_REMOVED}, * @return one of {@link #MEDIA_UNKNOWN}, {@link #MEDIA_REMOVED},
* {@link #MEDIA_UNMOUNTED}, {@link #MEDIA_CHECKING}, * {@link #MEDIA_UNMOUNTED}, {@link #MEDIA_CHECKING},
@@ -665,7 +668,8 @@ public class Environment {
} }
/** /**
* Returns whether the primary "external" storage device is removable. * Returns whether the primary shared/external storage media is physically
* removable.
* *
* @return true if the storage device can be removed (such as an SD card), * @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 * or false if the storage device is built in and cannot be
@@ -678,8 +682,8 @@ public class Environment {
} }
/** /**
* Returns whether the storage device that provides the given path is * Returns whether the shared/external storage media at the given path is
* removable. * physically removable.
* *
* @return true if the storage device can be removed (such as an SD card), * @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 * or false if the storage device is built in and cannot be
@@ -697,9 +701,15 @@ public class Environment {
} }
/** /**
* Returns whether the primary "external" storage device is emulated. If * Returns whether the primary shared/external storage media is emulated.
* true, data stored on this device will be stored on a portion of the * <p>
* internal storage system. * 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
* {@link Context#getFilesDir()}, etc.
* <p>
* This returns true when emulated storage is backed by either internal
* storage or an adopted storage device.
* *
* @see DevicePolicyManager#setStorageEncryption(android.content.ComponentName, * @see DevicePolicyManager#setStorageEncryption(android.content.ComponentName,
* boolean) * boolean)
@@ -711,9 +721,16 @@ public class Environment {
} }
/** /**
* Returns whether the storage device that provides the given path is * Returns whether the shared/external storage media at the given path is
* emulated. If true, data stored on this device will be stored on a portion * emulated.
* of the internal storage system. * <p>
* 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
* {@link Context#getFilesDir()}, etc.
* <p>
* This returns true when emulated storage is backed by either internal
* storage or an adopted storage device.
* *
* @throws IllegalArgumentException if the path is not a valid storage * @throws IllegalArgumentException if the path is not a valid storage
* device. * device.