Merge "Update docs for multi-user storage behavior." into jb-mr1-dev

Author: jsharkey

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 @@ public abstract FileOutputStream openFileOutput(String name, int mode)
      * 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 @@ public abstract FileOutputStream openFileOutput(String name, int mode)
      * {@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 @@ public abstract FileOutputStream openFileOutput(String name, int mode)
      * 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 @@ public abstract FileOutputStream openFileOutput(String name, int mode)
      * 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

core/java/android/os/Environment.java

@@ -274,6 +274,10 @@ public static File getDataDirectory() {
      * 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 @@ public static File getDataDirectory() {
      * 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 @@ public static File getEmulatedStorageObbSource() {
      * 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 @@ public static File getExternalStorageAppCacheDirectory(String packageName) {
     }
 
     /**
-     * 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 @@ public static File getDownloadCacheDirectory() {
     /**
      * Gets the current state of the primary "external" storage device.
      * 
-     * <p>See {@link #getExternalStorageDirectory()} for more information.
+     * @see #getExternalStorageDirectory()
      */
     public static String getExternalStorageState() {
         try {