Add CancellationSignal support to file operations.
Since ContentProvider file operations can end up doing substantial
network I/O before returning the file, allow clients to cancel their
file requests with CancellationSignal.
Ideally this would only be needed for openFile(), but ContentResolver
heavily relies on openAssetFile() and openTypedAssetFile() for common
cases.
Also improve documentation to mention reliable ParcelFileDescriptors
and encourage developers to move away from "rw" combination modes,
since they restrict provider flexibility. Mention more about places
where pipes or socket pairs could be returned.
Improve DocumentsContract documentation.
Bug: 10329944
Change-Id: I49b2825ea433eb051624c4da3b77612fe3ffc99c
diff --git a/core/java/android/content/Intent.java b/core/java/android/content/Intent.java
index 017ad98..be13620 100644
--- a/core/java/android/content/Intent.java
+++ b/core/java/android/content/Intent.java
@@ -35,6 +35,7 @@
import android.os.Parcel;
import android.os.Parcelable;
import android.os.StrictMode;
+import android.provider.DocumentsContract;
import android.util.AttributeSet;
import android.util.Log;
@@ -2650,11 +2651,16 @@
* multiple selection), then it can specify {@link #EXTRA_ALLOW_MULTIPLE} to
* indicate this.
* <p>
- * All returned URIs can be opened as a stream with
- * {@link ContentResolver#openInputStream(Uri)}.
+ * 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.
+ * so that any receiver can access it. If multiple documents were selected,
+ * they are returned in {@link #getClipData()}.
+ *
+ * @see DocumentsContract
+ * @see DocumentsContract#getOpenDocuments(Context)
*/
@SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
public static final String ACTION_OPEN_DOCUMENT = "android.intent.action.OPEN_DOCUMENT";
@@ -2669,11 +2675,14 @@
* optionally hint at the MIME type being created by setting
* {@link #setType(String)}.
* <p>
- * All returned URIs can be opened as a stream with
- * {@link ContentResolver#openOutputStream(Uri)}.
+ * 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.
+ *
+ * @see DocumentsContract
*/
@SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
public static final String ACTION_CREATE_DOCUMENT = "android.intent.action.CREATE_DOCUMENT";