4 files changed, 93 insertions, 4 deletions
diff --git a/core/java/android/app/PendingIntent.java b/core/java/android/app/PendingIntent.java
index 2897ee0f5569..37804e9103a5 100644
--- a/core/java/android/app/PendingIntent.java
+++ b/core/java/android/app/PendingIntent.java
@@ -41,7 +41,7 @@ import android.util.AndroidException;
  * 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 @@ public final class PendingIntent implements Parcelable {
      * 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 @@ public final class PendingIntent implements Parcelable {
      * 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 @@ public final class PendingIntent implements Parcelable {
      * 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 @@ public final class PendingIntent implements Parcelable {
      * 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 @@ public final class PendingIntent implements Parcelable {
      * 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 @@ public final class PendingIntent implements Parcelable {
      * {@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 @@ public final class PendingIntent implements Parcelable {
      * 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 @@ public final class PendingIntent implements Parcelable {
      * 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 @@ public final class PendingIntent implements Parcelable {
      * {@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 90ee0ac8a390..e9b800dc305a 100644
--- a/core/java/android/content/ContentProvider.java
+++ b/core/java/android/content/ContentProvider.java
@@ -871,6 +871,18 @@ public abstract class ContentProvider implements ComponentCallbacks2 {
      * 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 @@ public abstract class ContentProvider implements ComponentCallbacks2 {
      *
      * @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 @@ public abstract class ContentProvider implements ComponentCallbacks2 {
      * {@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 @@ public abstract class ContentProvider implements ComponentCallbacks2 {
      * 
      * @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 @@ public abstract class ContentProvider implements ComponentCallbacks2 {
      * 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 434946c65c6e..034f96fbe899 100644
--- a/core/java/android/content/Intent.java
+++ b/core/java/android/content/Intent.java
@@ -2610,7 +2610,8 @@ public class Intent implements Parcelable, Cloneable {
     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 3b0d846cd235..5e65b59d01d4 100644
--- a/core/java/android/content/IntentFilter.java
+++ b/core/java/android/content/IntentFilter.java
@@ -86,7 +86,8 @@ import java.util.Set;
  * <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