Add new Intent API for associating a ClipData with an Intent.

Allows applications to propagate multiple URI grants through an
Intent.

Later on, we should probably redefine the share actions to be
based on this ClipData with the old extras-based approach only
there for compatibility.  Even if we don't do that, though, this
allows you to do a multi-select share that grants multiple URI
permissions by stuffing the URIs in a ClipData.

Also add some documentation in various places telling people how
they can grant URI permissions.

Change-Id: Id4ba8e72c11caf7e1f1f438cb7af058d1586a37c

1 files changed, 13 insertions, 1 deletions

diff --git a/core/java/android/app/Service.java b/core/java/android/app/Service.java
index 35bd8c08a713..be4b8af6fb49 100644
--- a/core/java/android/app/Service.java
+++ b/core/java/android/app/Service.java
@@ -163,7 +163,19 @@ import java.io.PrintWriter;
  * {@link android.R.styleable#AndroidManifestUsesPermission <uses-permission>}
  * element in their own manifest to be able to start, stop, or bind to
  * the service.
- * 
+ *
+ * <p>As of {@link android.os.Build.VERSION_CODES#GINGERBREAD}, when using
+ * {@link Context#startService(Intent) Context.startService(Intent)}, you can
+ * also set {@link Intent#FLAG_GRANT_READ_URI_PERMISSION
+ * Intent.FLAG_GRANT_READ_URI_PERMISSION} and/or {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION
+ * Intent.FLAG_GRANT_WRITE_URI_PERMISSION} on the Intent.  This will grant the
+ * Service temporary access to the specific URIs in the Intent.  Access will
+ * remain until the Service has called {@link #stopSelf(int)} for that start
+ * command or a later one, or until the Service has been completely stopped.
+ * This works for granting access to the other apps that have not requested
+ * the permission protecting the Service, or even when the Service is not
+ * exported at all.
+ *
  * <p>In addition, a service can protect individual IPC calls into it with
  * permissions, by calling the
  * {@link #checkCallingPermission}