Fix issue #8228463: contradicting public documentation on what...
...Intents match an IntentFilter that has no action specified
And various other doc improvements.
Change-Id: I6d881c8aed56c552e36d5db5df4f74c6aa718da7
diff --git a/core/java/android/app/PendingIntent.java b/core/java/android/app/PendingIntent.java
index 2897ee0..37804e9 100644
--- a/core/java/android/app/PendingIntent.java
+++ b/core/java/android/app/PendingIntent.java
@@ -41,7 +41,7 @@
* you are granting it the right to perform the operation you have specified
* as if the other application was yourself (with the same permissions and
* identity). As such, you should be careful about how you build the PendingIntent:
- * often, for example, the base Intent you supply will have the component
+ * almost always, for example, the base Intent you supply should have the component
* name explicitly set to one of your own components, to ensure it is ultimately
* sent there and nowhere else.
*
@@ -200,6 +200,11 @@
* existing activity, so you must use the {@link Intent#FLAG_ACTIVITY_NEW_TASK
* Intent.FLAG_ACTIVITY_NEW_TASK} launch flag in the Intent.
*
+ * <p class="note">For security reasons, the {@link android.content.Intent}
+ * you supply here should almost always be an <em>explicit intent</em>,
+ * that is specify an explicit component to be delivered to through
+ * {@link Intent#setClass(android.content.Context, Class)} Intent.setClass</p>
+ *
* @param context The Context in which this PendingIntent should start
* the activity.
* @param requestCode Private request code for the sender (currently
@@ -227,6 +232,11 @@
* existing activity, so you must use the {@link Intent#FLAG_ACTIVITY_NEW_TASK
* Intent.FLAG_ACTIVITY_NEW_TASK} launch flag in the Intent.
*
+ * <p class="note">For security reasons, the {@link android.content.Intent}
+ * you supply here should almost always be an <em>explicit intent</em>,
+ * that is specify an explicit component to be delivered to through
+ * {@link Intent#setClass(android.content.Context, Class)} Intent.setClass</p>
+ *
* @param context The Context in which this PendingIntent should start
* the activity.
* @param requestCode Private request code for the sender (currently
@@ -313,6 +323,11 @@
* UI the user actually sees when the intents are started.
* </p>
*
+ * <p class="note">For security reasons, the {@link android.content.Intent} objects
+ * you supply here should almost always be <em>explicit intents</em>,
+ * that is specify an explicit component to be delivered to through
+ * {@link Intent#setClass(android.content.Context, Class)} Intent.setClass</p>
+ *
* @param context The Context in which this PendingIntent should start
* the activity.
* @param requestCode Private request code for the sender (currently
@@ -359,6 +374,11 @@
* UI the user actually sees when the intents are started.
* </p>
*
+ * <p class="note">For security reasons, the {@link android.content.Intent} objects
+ * you supply here should almost always be <em>explicit intents</em>,
+ * that is specify an explicit component to be delivered to through
+ * {@link Intent#setClass(android.content.Context, Class)} Intent.setClass</p>
+ *
* @param context The Context in which this PendingIntent should start
* the activity.
* @param requestCode Private request code for the sender (currently
@@ -423,6 +443,11 @@
* Retrieve a PendingIntent that will perform a broadcast, like calling
* {@link Context#sendBroadcast(Intent) Context.sendBroadcast()}.
*
+ * <p class="note">For security reasons, the {@link android.content.Intent}
+ * you supply here should almost always be an <em>explicit intent</em>,
+ * that is specify an explicit component to be delivered to through
+ * {@link Intent#setClass(android.content.Context, Class)} Intent.setClass</p>
+ *
* @param context The Context in which this PendingIntent should perform
* the broadcast.
* @param requestCode Private request code for the sender (currently
@@ -473,6 +498,11 @@
* {@link Context#startService Context.startService()}. The start
* arguments given to the service will come from the extras of the Intent.
*
+ * <p class="note">For security reasons, the {@link android.content.Intent}
+ * you supply here should almost always be an <em>explicit intent</em>,
+ * that is specify an explicit component to be delivered to through
+ * {@link Intent#setClass(android.content.Context, Class)} Intent.setClass</p>
+ *
* @param context The Context in which this PendingIntent should start
* the service.
* @param requestCode Private request code for the sender (currently
@@ -707,6 +737,15 @@
* sending the Intent. The returned string is supplied by the system, so
* that an application can not spoof its package.
*
+ * <p class="note">Be careful about how you use this. All this tells you is
+ * who created the PendingIntent. It does <strong>not</strong> tell you who
+ * handed the PendingIntent to you: that is, PendingIntent objects are intended to be
+ * passed between applications, so the PendingIntent you receive from an application
+ * could actually be one it received from another application, meaning the result
+ * you get here will identify the original application. Because of this, you should
+ * only use this information to identify who you expect to be interacting with
+ * through a {@link #send} call, not who gave you the PendingIntent.</p>
+ *
* @return The package name of the PendingIntent, or null if there is
* none associated with it.
*/
@@ -726,6 +765,15 @@
* sending the Intent. The returned integer is supplied by the system, so
* that an application can not spoof its uid.
*
+ * <p class="note">Be careful about how you use this. All this tells you is
+ * who created the PendingIntent. It does <strong>not</strong> tell you who
+ * handed the PendingIntent to you: that is, PendingIntent objects are intended to be
+ * passed between applications, so the PendingIntent you receive from an application
+ * could actually be one it received from another application, meaning the result
+ * you get here will identify the original application. Because of this, you should
+ * only use this information to identify who you expect to be interacting with
+ * through a {@link #send} call, not who gave you the PendingIntent.</p>
+ *
* @return The uid of the PendingIntent, or -1 if there is
* none associated with it.
*/
@@ -747,6 +795,15 @@
* {@link android.os.Process#myUserHandle() Process.myUserHandle()} for
* more explanation of user handles.
*
+ * <p class="note">Be careful about how you use this. All this tells you is
+ * who created the PendingIntent. It does <strong>not</strong> tell you who
+ * handed the PendingIntent to you: that is, PendingIntent objects are intended to be
+ * passed between applications, so the PendingIntent you receive from an application
+ * could actually be one it received from another application, meaning the result
+ * you get here will identify the original application. Because of this, you should
+ * only use this information to identify who you expect to be interacting with
+ * through a {@link #send} call, not who gave you the PendingIntent.</p>
+ *
* @return The user handle of the PendingIntent, or null if there is
* none associated with it.
*/
diff --git a/core/java/android/content/ContentProvider.java b/core/java/android/content/ContentProvider.java
index 90ee0ac..e9b800d 100644
--- a/core/java/android/content/ContentProvider.java
+++ b/core/java/android/content/ContentProvider.java
@@ -871,6 +871,18 @@
* their responsibility to close it when done. That is, the implementation
* of this method should create a new ParcelFileDescriptor for each call.
*
+ * <p class="note">For use in Intents, you will want to implement {@link #getType}
+ * to return the appropriate MIME type for the data returned here with
+ * the same URI. This will allow intent resolution to automatically determine the data MIME
+ * type and select the appropriate matching targets as part of its operation.</p>
+ *
+ * <p class="note">For better interoperability with other applications, it is recommended
+ * that for any URIs that can be opened, you also support queries on them
+ * containing at least the columns specified by {@link android.provider.OpenableColumns}.
+ * You may also want to support other common columns if you have additional meta-data
+ * to supply, such as {@link android.provider.MediaStore.MediaColumns#DATE_ADDED}
+ * in {@link android.provider.MediaStore.MediaColumns}.</p>
+ *
* @param uri The URI whose file is to be opened.
* @param mode Access mode for the file. May be "r" for read-only access,
* "rw" for read and write access, or "rwt" for read and write access
@@ -886,6 +898,7 @@
*
* @see #openAssetFile(Uri, String)
* @see #openFileHelper(Uri, String)
+ * @see #getType(android.net.Uri)
*/
public ParcelFileDescriptor openFile(Uri uri, String mode)
throws FileNotFoundException {
@@ -913,6 +926,15 @@
* {@link AssetFileDescriptor#UNKNOWN_LENGTH} to be compatible with
* applications that can not handle sub-sections of files.</p>
*
+ * <p class="note">For use in Intents, you will want to implement {@link #getType}
+ * to return the appropriate MIME type for the data returned here with
+ * the same URI. This will allow intent resolution to automatically determine the data MIME
+ * type and select the appropriate matching targets as part of its operation.</p>
+ *
+ * <p class="note">For better interoperability with other applications, it is recommended
+ * that for any URIs that can be opened, you also support queries on them
+ * containing at least the columns specified by {@link android.provider.OpenableColumns}.</p>
+ *
* @param uri The URI whose file is to be opened.
* @param mode Access mode for the file. May be "r" for read-only access,
* "w" for write-only access (erasing whatever data is currently in
@@ -930,6 +952,7 @@
*
* @see #openFile(Uri, String)
* @see #openFileHelper(Uri, String)
+ * @see #getType(android.net.Uri)
*/
public AssetFileDescriptor openAssetFile(Uri uri, String mode)
throws FileNotFoundException {
@@ -1009,12 +1032,19 @@
* perform data conversions to generate data of the desired type.
*
* <p>The default implementation compares the given mimeType against the
- * result of {@link #getType(Uri)} and, if the match, simple calls
+ * result of {@link #getType(Uri)} and, if they match, simply calls
* {@link #openAssetFile(Uri, String)}.
*
* <p>See {@link ClipData} for examples of the use and implementation
* of this method.
*
+ * <p class="note">For better interoperability with other applications, it is recommended
+ * that for any URIs that can be opened, you also support queries on them
+ * containing at least the columns specified by {@link android.provider.OpenableColumns}.
+ * You may also want to support other common columns if you have additional meta-data
+ * to supply, such as {@link android.provider.MediaStore.MediaColumns#DATE_ADDED}
+ * in {@link android.provider.MediaStore.MediaColumns}.</p>
+ *
* @param uri The data in the content provider being queried.
* @param mimeTypeFilter The type of data the client desires. May be
* a pattern, such as *\/*, if the caller does not have specific type
diff --git a/core/java/android/content/Intent.java b/core/java/android/content/Intent.java
index 434946c..034f96f 100644
--- a/core/java/android/content/Intent.java
+++ b/core/java/android/content/Intent.java
@@ -2610,7 +2610,8 @@
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 OpenableColumns
+ * 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.
*/
@SdkConstant(SdkConstantType.INTENT_CATEGORY)
diff --git a/core/java/android/content/IntentFilter.java b/core/java/android/content/IntentFilter.java
index 3b0d846..5e65b59 100644
--- a/core/java/android/content/IntentFilter.java
+++ b/core/java/android/content/IntentFilter.java
@@ -86,7 +86,8 @@
* <strong>data scheme+authority+path</strong> if specified) must match.
*
* <p><strong>Action</strong> matches if any of the given values match the
- * Intent action, <em>or</em> if no actions were specified in the filter.
+ * Intent action; if the filter specifies no actions, then it will only match
+ * Intents that do not contain an action.
*
* <p><strong>Data Type</strong> matches if any of the given values match the
* Intent type. The Intent