drgreen/android_frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Jeff Sharkey
2013-10-15 23:45:10 +00:00
committed by Android (Google) Code Review
parent 3cf56085f1 adef88a0a9
commit e3924ca486
2 changed files with 94 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
core/java/android/content/ContentResolver.java
View File

@ -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.

131
core/java/android/content/Intent.java
View File

@ -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
* documents. Both read and write access to the documents will be granted
* until explicitly revoked by the user.
* Activity Action: Allow the user to select and return one or more existing
* documents. When invoked, the system will display the various
* {@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
* photos, by setting one or more MIME types in {@link #EXTRA_MIME_TYPES}.
* Each document is represented as a {@code content://} URI backed by a
* {@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
* indicate this.
* multiple selection), then you can specify {@link #EXTRA_ALLOW_MULTIPLE}
* 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
* so that any receiver can access it. If multiple documents were selected,
* they are returned in {@link #getClipData()}.
* Output: The URI of the item that was picked. This must be a
* {@code content://} URI so that any receiver can access it. If multiple
* 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
* write access to the document will be granted until explicitly revoked by
* the user.
* Activity Action: Allow the user to create a new document. When invoked,
* the system will display the various {@link DocumentsProvider} instances
* 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},
* but the user may change this value before creating the file. Callers can
* optionally hint at the MIME type being created by setting
* {@link #setType(String)}.
* Each document is represented as a {@code content://} URI backed by a
* {@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>
* 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
* so that any receiver can access it.
* Output: The URI of the item that was created. This must be a
* {@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
* ContentResolver.openInputStream. Openable URIs must support the columns in
* {@link android.provider.OpenableColumns}
* when queried, though it is allowable for those columns to be blank.
* Used to indicate that an intent only wants URIs that can be opened with
* {@link ContentResolver#openFileDescriptor(Uri, String)}. Openable URIs
* must support at least the columns defined in {@link OpenableColumns} when
* 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,24 +3251,29 @@ public class Intent implements Parcelable, Cloneable {
"android.intent.extra.client_intent";
/**
* Used to indicate that a {@link #ACTION_GET_CONTENT} intent should only return
* data that is on the local device. This is a boolean extra; the default
* is false. If true, an implementation of ACTION_GET_CONTENT should only allow
* the user to select media that is already on the device, not requiring it
* be downloaded from a remote service when opened. Another way to look
* at it is that such content should generally have a "_data" column to the
* path of the content on local external storage.
* Extra used to indicate that an intent should only return data that is on
* the local device. This is a boolean extra; the default is false. If true,
* an implementation should only allow the user to select data that is
* already on the device, not requiring it be downloaded from a remote
* service when opened.
*
* @see #ACTION_GET_CONTENT
* @see #ACTION_OPEN_DOCUMENT
* @see #ACTION_CREATE_DOCUMENT
*/
public static final String EXTRA_LOCAL_ONLY =
"android.intent.extra.LOCAL_ONLY";
/**
* Used to indicate that a {@link #ACTION_GET_CONTENT} intent can allow the
* user to select and return multiple items. This is a boolean extra; the default
* is false. If true, an implementation of ACTION_GET_CONTENT is allowed to
* present the user with a UI where they can pick multiple items that are all
* returned to the caller. When this happens, they should be returned as
* the {@link #getClipData()} part of the result Intent.
* Extra used to indicate that an intent can allow the user to select and
* return multiple items. This is a boolean extra; the default is false. If
* true, an implementation is allowed to present the user with a UI where
* they can pick multiple items that are all returned to the caller. When
* this happens, they should be returned as the {@link #getClipData()} part
* of the result Intent.
*
* @see #ACTION_GET_CONTENT
* @see #ACTION_OPEN_DOCUMENT
*/
public static final String EXTRA_ALLOW_MULTIPLE =
"android.intent.extra.ALLOW_MULTIPLE";
@ -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
* {@link #ACTION_GET_CONTENT} or {@link #ACTION_OPEN_DOCUMENT}. The type of the
* extra is <code>ArrayList&lt;String&gt;</code>.
* Extra used to communicate a set of acceptable MIME types. The type of the
* extra is {@code String[]}. Values may be a combination of concrete MIME
* 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;