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

2 files changed, 10 insertions, 6 deletions

diff --git a/test-runner/src/android/test/mock/MockContentProvider.java b/test-runner/src/android/test/mock/MockContentProvider.java
index 373f24a..596ea0a 100644
--- a/test-runner/src/android/test/mock/MockContentProvider.java
+++ b/test-runner/src/android/test/mock/MockContentProvider.java
@@ -83,13 +83,15 @@ public class MockContentProvider extends ContentProvider {
         }
 
         @Override
-        public AssetFileDescriptor openAssetFile(String callingPackage, Uri url, String mode)
+        public AssetFileDescriptor openAssetFile(
+                String callingPackage, Uri url, String mode, ICancellationSignal signal)
                 throws RemoteException, FileNotFoundException {
             return MockContentProvider.this.openAssetFile(url, mode);
         }
 
         @Override
-        public ParcelFileDescriptor openFile(String callingPackage, Uri url, String mode)
+        public ParcelFileDescriptor openFile(
+                String callingPackage, Uri url, String mode, ICancellationSignal signal)
                 throws RemoteException, FileNotFoundException {
             return MockContentProvider.this.openFile(url, mode);
         }
@@ -126,7 +128,7 @@ public class MockContentProvider extends ContentProvider {
 
         @Override
         public AssetFileDescriptor openTypedAssetFile(String callingPackage, Uri url,
-                String mimeType, Bundle opts)
+                String mimeType, Bundle opts, ICancellationSignal signal)
                 throws RemoteException, FileNotFoundException {
             return MockContentProvider.this.openTypedAssetFile(url, mimeType, opts);
         }
diff --git a/test-runner/src/android/test/mock/MockIContentProvider.java b/test-runner/src/android/test/mock/MockIContentProvider.java
index 2b4fce6..b14ce49 100644
--- a/test-runner/src/android/test/mock/MockIContentProvider.java
+++ b/test-runner/src/android/test/mock/MockIContentProvider.java
@@ -61,11 +61,13 @@ public class MockIContentProvider implements IContentProvider {
         throw new UnsupportedOperationException("unimplemented mock method");
     }
 
-    public ParcelFileDescriptor openFile(String callingPackage, Uri url, String mode) {
+    public ParcelFileDescriptor openFile(
+            String callingPackage, Uri url, String mode, ICancellationSignal signal) {
         throw new UnsupportedOperationException("unimplemented mock method");
     }
 
-    public AssetFileDescriptor openAssetFile(String callingPackage, Uri uri, String mode) {
+    public AssetFileDescriptor openAssetFile(
+            String callingPackage, Uri uri, String mode, ICancellationSignal signal) {
         throw new UnsupportedOperationException("unimplemented mock method");
     }
 
@@ -104,7 +106,7 @@ public class MockIContentProvider implements IContentProvider {
     }
 
     public AssetFileDescriptor openTypedAssetFile(String callingPackage, Uri url, String mimeType,
-            Bundle opts) throws RemoteException, FileNotFoundException {
+            Bundle opts, ICancellationSignal signal) throws RemoteException, FileNotFoundException {
         throw new UnsupportedOperationException("unimplemented mock method");
     }