Merge "Improve OPEN/CREATE_DOC docs." into klp-dev

core/java/android/content/ContentResolver.java

@@ -1627,9 +1627,9 @@ public abstract class ContentResolver {
     }
 
     /**
-     * Take a persistable Uri permission grant that has been offered. Once
+     * Take a persistable URI permission grant that has been offered. Once
      * taken, the permission grant will be remembered across device reboots.
-     * Only Uri permissions granted with
+     * Only URI permissions granted with
      * {@link Intent#FLAG_GRANT_PERSISTABLE_URI_PERMISSION} can be persisted. If
      * the grant has already been persisted, taking it again will touch
      * {@link UriPermission#getPersistedTime()}.
@@ -1644,7 +1644,7 @@ public abstract class ContentResolver {
     }
 
     /**
-     * Relinquish a persisted Uri permission grant. The Uri must have been
+     * Relinquish a persisted URI permission grant. The URI must have been
      * previously made persistent with
      * {@link #takePersistableUriPermission(Uri, int)}. Any non-persistent
      * grants to the calling package will remain intact.
@@ -1659,7 +1659,7 @@ public abstract class ContentResolver {
     }
 
     /**
-     * Return list of all Uri permission grants that have been persisted by the
+     * Return list of all URI permission grants that have been persisted by the
      * calling app. That is, the returned permissions have been granted
      * <em>to</em> the calling app. Only persistable grants taken with
      * {@link #takePersistableUriPermission(Uri, int)} are returned.
@@ -1677,7 +1677,7 @@ public abstract class ContentResolver {
     }
 
     /**
-     * Return list of all persisted Uri permission grants that are hosted by the
+     * Return list of all persisted URI permission grants that are hosted by the
      * calling app. That is, the returned permissions have been granted
      * <em>from</em> the calling app. Only grants taken with
      * {@link #takePersistableUriPermission(Uri, int)} are returned.

core/java/android/content/Intent.java

@@ -36,6 +36,8 @@ import android.os.Parcel;
 import android.os.Parcelable;
 import android.os.StrictMode;
 import android.provider.DocumentsContract;
+import android.provider.DocumentsProvider;
+import android.provider.OpenableColumns;
 import android.util.AttributeSet;
 import android.util.Log;
 
@@ -45,7 +47,6 @@ import java.io.IOException;
 import java.io.Serializable;
 import java.net.URISyntaxException;
 import java.util.ArrayList;
-import java.util.Iterator;
 import java.util.List;
 import java.util.Locale;
 import java.util.Set;
@@ -2621,49 +2622,76 @@ public class Intent implements Parcelable, Cloneable {
     public static final String ACTION_GLOBAL_BUTTON = "android.intent.action.GLOBAL_BUTTON";
 
     /**
-     * Activity Action: Allow the user to select and open one or more existing
+     * Activity Action: Allow the user to select and return one or more existing
-     * documents. Both read and write access to the documents will be granted
+     * documents. When invoked, the system will display the various
-     * until explicitly revoked by the user.
+     * {@link DocumentsProvider} instances installed on the device, letting the
+     * user interactively navigate through them. These documents include local
+     * media, such as photos and video, and documents provided by installed
+     * cloud storage providers.
      * <p>
-     * Callers can restrict selection to a specific kind of data, such as
+     * Each document is represented as a {@code content://} URI backed by a
-     * photos, by setting one or more MIME types in {@link #EXTRA_MIME_TYPES}.
+     * {@link DocumentsProvider}, which can be opened as a stream with
+     * {@link ContentResolver#openFileDescriptor(Uri, String)}, or queried for
+     * {@link android.provider.DocumentsContract.Document} metadata.
+     * <p>
+     * All selected documents are returned to the calling application with
+     * persistable read and write permission grants. If you want to maintain
+     * access to the documents across device reboots, you need to explicitly
+     * take the persistable permissions using
+     * {@link ContentResolver#takePersistableUriPermission(Uri, int)}.
+     * <p>
+     * Callers can restrict document selection to a specific kind of data, such
+     * as photos, by setting one or more MIME types in
+     * {@link #EXTRA_MIME_TYPES}.
      * <p>
      * If the caller can handle multiple returned items (the user performing
-     * multiple selection), then it can specify {@link #EXTRA_ALLOW_MULTIPLE} to
+     * multiple selection), then you can specify {@link #EXTRA_ALLOW_MULTIPLE}
-     * indicate this.
+     * to indicate this.
      * <p>
      * Callers must include {@link #CATEGORY_OPENABLE} in the Intent so that
      * returned URIs can be opened with
      * {@link ContentResolver#openFileDescriptor(Uri, String)}.
      * <p>
-     * Output: The URI of the item that was picked. This must be a content: URI
+     * Output: The URI of the item that was picked. This must be a
-     * so that any receiver can access it. If multiple documents were selected,
+     * {@code content://} URI so that any receiver can access it. If multiple
-     * they are returned in {@link #getClipData()}.
+     * documents were selected, they are returned in {@link #getClipData()}.
      *
      * @see DocumentsContract
-     * @see DocumentsContract#getOpenDocuments(Context)
+     * @see #ACTION_CREATE_DOCUMENT
+     * @see #FLAG_GRANT_PERSISTABLE_URI_PERMISSION
      */
     @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
     public static final String ACTION_OPEN_DOCUMENT = "android.intent.action.OPEN_DOCUMENT";
 
     /**
-     * Activity Action: Allow the user to create a new document. Both read and
+     * Activity Action: Allow the user to create a new document. When invoked,
-     * write access to the document will be granted until explicitly revoked by
+     * the system will display the various {@link DocumentsProvider} instances
-     * the user.
+     * installed on the device, letting the user navigate through them. The
+     * returned document may be a newly created document with no content, or it
+     * may be an existing document with the requested MIME type.
      * <p>
-     * Callers can provide a hint document name by setting {@link #EXTRA_TITLE},
+     * Each document is represented as a {@code content://} URI backed by a
-     * but the user may change this value before creating the file. Callers can
+     * {@link DocumentsProvider}, which can be opened as a stream with
-     * optionally hint at the MIME type being created by setting
+     * {@link ContentResolver#openFileDescriptor(Uri, String)}, or queried for
-     * {@link #setType(String)}.
+     * {@link android.provider.DocumentsContract.Document} metadata.
+     * <p>
+     * Callers must indicate the concrete MIME type of the document being
+     * created by setting {@link #setType(String)}. This MIME type cannot be
+     * changed after the document is created.
+     * <p>
+     * Callers can provide an initial display name through {@link #EXTRA_TITLE},
+     * but the user may change this value before creating the file.
      * <p>
      * Callers must include {@link #CATEGORY_OPENABLE} in the Intent so that
      * returned URIs can be opened with
      * {@link ContentResolver#openFileDescriptor(Uri, String)}.
      * <p>
-     * Output: The URI of the item that was created. This must be a content: URI
+     * Output: The URI of the item that was created. This must be a
-     * so that any receiver can access it.
+     * {@code content://} URI so that any receiver can access it.
      *
      * @see DocumentsContract
+     * @see #ACTION_OPEN_DOCUMENT
+     * @see #FLAG_GRANT_PERSISTABLE_URI_PERMISSION
      */
     @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
     public static final String ACTION_CREATE_DOCUMENT = "android.intent.action.CREATE_DOCUMENT";
@@ -2787,11 +2815,16 @@ public class Intent implements Parcelable, Cloneable {
      * experience).
      */
     public static final String CATEGORY_SAMPLE_CODE = "android.intent.category.SAMPLE_CODE";
+
     /**
-     * Used to indicate that a GET_CONTENT intent only wants URIs that can be opened with
+     * Used to indicate that an intent only wants URIs that can be opened with
-     * ContentResolver.openInputStream. Openable URIs must support the columns in
+     * {@link ContentResolver#openFileDescriptor(Uri, String)}. Openable URIs
-     * {@link android.provider.OpenableColumns}
+     * must support at least the columns defined in {@link OpenableColumns} when
-     * when queried, though it is allowable for those columns to be blank.
+     * queried.
+     *
+     * @see #ACTION_GET_CONTENT
+     * @see #ACTION_OPEN_DOCUMENT
+     * @see #ACTION_CREATE_DOCUMENT
      */
     @SdkConstant(SdkConstantType.INTENT_CATEGORY)
     public static final String CATEGORY_OPENABLE = "android.intent.category.OPENABLE";
@@ -3218,27 +3251,32 @@ public class Intent implements Parcelable, Cloneable {
             "android.intent.extra.client_intent";
 
     /**
-     * Used to indicate that a {@link #ACTION_GET_CONTENT} intent should only return
+     * Extra used to indicate that an intent should only return data that is on
-     * data that is on the local device.  This is a boolean extra; the default
+     * the local device. This is a boolean extra; the default is false. If true,
-     * is false.  If true, an implementation of ACTION_GET_CONTENT should only allow
+     * an implementation should only allow the user to select data that is
-     * the user to select media that is already on the device, not requiring it
+     * already on the device, not requiring it be downloaded from a remote
-     * be downloaded from a remote service when opened.  Another way to look
+     * service when opened.
-     * at it is that such content should generally have a "_data" column to the
+     *
-     * path of the content on local external storage.
+     * @see #ACTION_GET_CONTENT
+     * @see #ACTION_OPEN_DOCUMENT
+     * @see #ACTION_CREATE_DOCUMENT
      */
     public static final String EXTRA_LOCAL_ONLY =
-        "android.intent.extra.LOCAL_ONLY";
+            "android.intent.extra.LOCAL_ONLY";
 
     /**
-     * Used to indicate that a {@link #ACTION_GET_CONTENT} intent can allow the
+     * Extra used to indicate that an intent can allow the user to select and
-     * user to select and return multiple items.  This is a boolean extra; the default
+     * return multiple items. This is a boolean extra; the default is false. If
-     * is false.  If true, an implementation of ACTION_GET_CONTENT is allowed to
+     * true, an implementation is allowed to present the user with a UI where
-     * present the user with a UI where they can pick multiple items that are all
+     * they can pick multiple items that are all returned to the caller. When
-     * returned to the caller.  When this happens, they should be returned as
+     * this happens, they should be returned as the {@link #getClipData()} part
-     * the {@link #getClipData()} part of the result Intent.
+     * of the result Intent.
+     *
+     * @see #ACTION_GET_CONTENT
+     * @see #ACTION_OPEN_DOCUMENT
      */
     public static final String EXTRA_ALLOW_MULTIPLE =
-        "android.intent.extra.ALLOW_MULTIPLE";
+            "android.intent.extra.ALLOW_MULTIPLE";
 
     /**
      * The userHandle carried with broadcast intents related to addition, removal and switching of
@@ -3272,9 +3310,13 @@ public class Intent implements Parcelable, Cloneable {
             "android.intent.extra.restrictions_intent";
 
     /**
-     * Extra used to communicate set of acceptable MIME types for
+     * Extra used to communicate a set of acceptable MIME types. The type of the
-     * {@link #ACTION_GET_CONTENT} or {@link #ACTION_OPEN_DOCUMENT}. The type of the
+     * extra is {@code String[]}. Values may be a combination of concrete MIME
-     * extra is <code>ArrayList&lt;String&gt;</code>.
+     * types (such as "image/png") and/or partial MIME types (such as
+     * "audio/*").
+     *
+     * @see #ACTION_GET_CONTENT
+     * @see #ACTION_OPEN_DOCUMENT
      */
     public static final String EXTRA_MIME_TYPES = "android.intent.extra.MIME_TYPES";
 
@@ -3295,7 +3337,7 @@ public class Intent implements Parcelable, Cloneable {
 
     /**
      * If set, the recipient of this Intent will be granted permission to
-     * perform read operations on the Uri in the Intent's data and any URIs
+     * perform read operations on the URI in the Intent's data and any URIs
      * specified in its ClipData.  When applying to an Intent's ClipData,
      * all URIs as well as recursive traversals through data or other ClipData
      * in Intent items will be granted; only the grant flags of the top-level
@@ -3304,7 +3346,7 @@ public class Intent implements Parcelable, Cloneable {
     public static final int FLAG_GRANT_READ_URI_PERMISSION = 0x00000001;
     /**
      * If set, the recipient of this Intent will be granted permission to
-     * perform write operations on the Uri in the Intent's data and any URIs
+     * perform write operations on the URI in the Intent's data and any URIs
      * specified in its ClipData.  When applying to an Intent's ClipData,
      * all URIs as well as recursive traversals through data or other ClipData
      * in Intent items will be granted; only the grant flags of the top-level
@@ -3339,7 +3381,7 @@ public class Intent implements Parcelable, Cloneable {
 
     /**
      * When combined with {@link #FLAG_GRANT_READ_URI_PERMISSION} and/or
-     * {@link #FLAG_GRANT_WRITE_URI_PERMISSION}, the Uri permission grant can be
+     * {@link #FLAG_GRANT_WRITE_URI_PERMISSION}, the URI permission grant can be
      * persisted across device reboots until explicitly revoked with
      * {@link Context#revokeUriPermission(Uri, int)}. This flag only offers the
      * grant for possible persisting; the receiving application must call
@@ -3349,6 +3391,7 @@ public class Intent implements Parcelable, Cloneable {
      * @see ContentResolver#takePersistableUriPermission(Uri, int)
      * @see ContentResolver#releasePersistableUriPermission(Uri, int)
      * @see ContentResolver#getPersistedUriPermissions()
+     * @see ContentResolver#getOutgoingPersistedUriPermissions()
      */
     public static final int FLAG_GRANT_PERSISTABLE_URI_PERMISSION = 0x00000040;