Update docs for multi-user storage behavior.
Define external storage as being isolated for each user, with the
caveat for shared OBB files. Also mention external storage
permissions.
Bug: 7384941
Change-Id: Ib156b5874c5587749d7bc066791e9e88d931b174
diff --git a/core/java/android/content/Context.java b/core/java/android/content/Context.java
index 201b43f..7aa2507 100644
--- a/core/java/android/content/Context.java
+++ b/core/java/android/content/Context.java
@@ -33,6 +33,7 @@
import android.os.Handler;
import android.os.Looper;
import android.os.UserHandle;
+import android.os.UserManager;
import android.util.AttributeSet;
import android.view.CompatibilityInfoHolder;
import android.view.Display;
@@ -587,6 +588,10 @@
* can read and write files placed here.
* </ul>
*
+ * <p>On devices with multiple users (as described by {@link UserManager}),
+ * each user has their own isolated external storage. Applications only
+ * have access to the external storage for the user they're running as.</p>
+ *
* <p>Here is an example of typical code to manipulate a file in
* an application's private storage:</p>
*
@@ -616,6 +621,9 @@
* {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java
* private_picture}
*
+ * <p>Writing to this path requires the
+ * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} permission.</p>
+ *
* @param type The type of files directory to return. May be null for
* the root of the files directory or one of
* the following Environment constants for a subdirectory:
@@ -641,6 +649,11 @@
* Return the directory where this application's OBB files (if there
* are any) can be found. Note if the application does not have any OBB
* files, this directory may not exist.
+ *
+ * <p>On devices with multiple users (as described by {@link UserManager}),
+ * multiple users may share the same OBB storage location. Applications
+ * should ensure that multiple instances running under different users
+ * don't interfere with each other.</p>
*/
public abstract File getObbDir();
@@ -689,6 +702,13 @@
* can read and write files placed here.
* </ul>
*
+ * <p>On devices with multiple users (as described by {@link UserManager}),
+ * each user has their own isolated external storage. Applications only
+ * have access to the external storage for the user they're running as.</p>
+ *
+ * <p>Writing to this path requires the
+ * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} permission.</p>
+ *
* @return Returns the path of the directory holding application cache files
* 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
diff --git a/core/java/android/os/Environment.java b/core/java/android/os/Environment.java
index 3315566..9030607 100644
--- a/core/java/android/os/Environment.java
+++ b/core/java/android/os/Environment.java
@@ -274,6 +274,10 @@
* built-in storage in a device that is distinct from the protected
* internal storage and can be mounted as a filesystem on a computer.</em></p>
*
+ * <p>On devices with multiple users (as described by {@link UserManager}),
+ * each user has their own isolated external storage. Applications only
+ * have access to the external storage for the user they're running as.</p>
+ *
* <p>In devices with multiple "external" storage directories (such as
* both secure app storage and mountable shared storage), this directory
* represents the "primary" external storage that the user will interact
@@ -286,7 +290,16 @@
* 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
- * {@link #getExternalStoragePublicDirectory}.
+ * {@link #getExternalStoragePublicDirectory}.</p>
+ *
+ * <p>Writing to this path requires the
+ * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} permission. In
+ * a future platform release, access to this path will require the
+ * {@link android.Manifest.permission#READ_EXTERNAL_STORAGE} permission,
+ * which is automatically granted if you hold the write permission.</p>
+ *
+ * <p>This path may change between platform versions, so applications
+ * should only persist relative paths.</p>
*
* <p>Here is an example of typical code to monitor the state of
* external storage:</p>
@@ -423,6 +436,10 @@
* to ensure you don't erase their files or get in the way of their own
* organization.
*
+ * <p>On devices with multiple users (as described by {@link UserManager}),
+ * each user has their own isolated external storage. Applications only
+ * have access to the external storage for the user they're running as.</p>
+ *
* <p>Here is an example of typical code to manipulate a picture on
* the public external storage:</p>
*
@@ -500,7 +517,10 @@
}
/**
- * Gets the Android Download/Cache content directory.
+ * Gets the Android download/cache content directory.
+ * <p>
+ * Access to this path requires the
+ * {@link android.Manifest.permission#ACCESS_CACHE_FILESYSTEM} permission.
*/
public static File getDownloadCacheDirectory() {
return DOWNLOAD_CACHE_DIRECTORY;
@@ -563,7 +583,7 @@
/**
* Gets the current state of the primary "external" storage device.
*
- * <p>See {@link #getExternalStorageDirectory()} for more information.
+ * @see #getExternalStorageDirectory()
*/
public static String getExternalStorageState() {
try {