am aec930b2: am f70d7b9a: am cf5ed42f: am df75bdcc: rewrite intent guide and add doc with intents supported by platform apps

* commit 'aec930b2c6c7e9ad2a7808a1636f7c0fae0164af':
  rewrite intent guide and add doc with intents supported by platform apps

core/java/android/app/PendingIntent.java

@@ -87,23 +87,25 @@ public final class PendingIntent implements Parcelable {
     private final IIntentSender mTarget;
 
     /**
-     * Flag for use with {@link #getActivity}, {@link #getBroadcast}, and
+     * Flag indicating that this PendingIntent can be used only once.
-     * {@link #getService}: this
+     * For use with {@link #getActivity}, {@link #getBroadcast}, and
-     * PendingIntent can only be used once.  If set, after
+     * {@link #getService}. <p>If set, after
      * {@link #send()} is called on it, it will be automatically
      * canceled for you and any future attempt to send through it will fail.
      */
     public static final int FLAG_ONE_SHOT = 1<<30;
     /**
-     * Flag for use with {@link #getActivity}, {@link #getBroadcast}, and
+     * Flag indicating that if the described PendingIntent already
-     * {@link #getService}: if the described PendingIntent already exists,
+     * exists, then simply return null instead of creating it.
-     * then simply return null instead of creating it.
+     * For use with {@link #getActivity}, {@link #getBroadcast}, and
+     * {@link #getService}.
      */
     public static final int FLAG_NO_CREATE = 1<<29;
     /**
-     * Flag for use with {@link #getActivity}, {@link #getBroadcast}, and
+     * Flag indicating that if the described PendingIntent already exists,
-     * {@link #getService}: if the described PendingIntent already exists,
+     * the current one should be canceled before generating a new one.
-     * the current one is canceled before generating a new one.  You can use
+     * For use with {@link #getActivity}, {@link #getBroadcast}, and
+     * {@link #getService}. <p>You can use
      * this to retrieve a new PendingIntent when you are only changing the
      * extra data in the Intent; by canceling the previous pending intent,
      * this ensures that only entities given the new data will be able to
@@ -112,10 +114,10 @@ public final class PendingIntent implements Parcelable {
      */
     public static final int FLAG_CANCEL_CURRENT = 1<<28;
     /**
-     * Flag for use with {@link #getActivity}, {@link #getBroadcast}, and
+     * Flag indicating that if the described PendingIntent already exists,
-     * {@link #getService}: if the described PendingIntent already exists,
+     * then keep it but replace its extra data with what is in this new
-     * then keep it but its replace its extra data with what is in this new
+     * Intent. For use with {@link #getActivity}, {@link #getBroadcast}, and
-     * Intent.  This can be used if you are creating intents where only the
+     * {@link #getService}. <p>This can be used if you are creating intents where only the
      * extras change, and don't care that any entities that received your
      * previous PendingIntent will be able to launch it with your new
      * extras even if they are not explicitly given to it.

docs/html/guide/components/services.jd

@@ -212,41 +212,35 @@ element. For example:</p>
 &lt;/manifest&gt;
 </pre>
 
+<p>See the <a
+href="{@docRoot}guide/topics/manifest/service-element.html">{@code &lt;service&gt;}</a> element
+reference for more information about declaring your service in the manifest.</p>
+
 <p>There are other attributes you can include in the <a
 href="{@docRoot}guide/topics/manifest/service-element.html">{@code &lt;service&gt;}</a> element to
 define properties such as permissions required to start the service and the process in
 which the service should run. The <a
 href="{@docRoot}guide/topics/manifest/service-element.html#nm">{@code android:name}</a>
 attribute is the only required attribute&mdash;it specifies the class name of the service. Once
-you publish your application, you should not change this name, because if you do, you might break
+you publish your application, you should not change this name, because if you do, you risk breaking
-some functionality where explicit intents are used to reference your service (read the blog post, <a
+code due to dependence on explicit intents to start or bind the service (read the blog post, <a
 href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">Things
 That Cannot Change</a>).
 
-<p>See the <a
+<p>To ensure your app is secure, <strong>always use an explicit intent when starting or binding
-href="{@docRoot}guide/topics/manifest/service-element.html">{@code &lt;service&gt;}</a> element
+your {@link android.app.Service}</strong> and do not declare intent filters for the service. If
-reference for more information about declaring your service in the manifest.</p>
+it's critical that you allow for some amount of ambiguity as to which service starts, you can
+supply intent filters for your services and exclude the component name from the {@link
+android.content.Intent}, but you then must set the package for the intent with {@link
+android.content.Intent#setPackage setPackage()}, which provides sufficient disambiguation for the
+target service.</p>
 
-<p>Just like an activity, a service can define intent filters that allow other components to
+<p>Additionally, you can ensure that your service is available to only your app by
-invoke the service using implicit intents. By declaring intent filters, components
+including the <a
-from any application installed on the user's device can potentially start your service if your
-service declares an intent filter that matches the intent another application passes to {@link
-android.content.Context#startService startService()}.</p>
-
-<p>If you plan on using your service only locally (other applications do not use it), then you
-don't need to (and should not) supply any intent filters. Without any intent filters, you must
-start the service using an intent that explicitly names the service class. More information
-about <a href="#StartingAService">starting a service</a> is discussed below.</p>
-
-<p>Additionally, you can ensure that your service is private to your application only if
-you include the <a
 href="{@docRoot}guide/topics/manifest/service-element.html#exported">{@code android:exported}</a>
-attribute and set it to {@code "false"}. This is effective even if your service supplies intent
+attribute and setting it to {@code "false"}. This effectively stops other apps from starting your
-filters.</p>
+service, even when using an explicit intent.</p>
 
-<p>For more information about creating intent filters for your service, see the <a
-href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>
-document.</p>
 
 
 

docs/html/guide/guide_toc.cs

@@ -68,9 +68,16 @@
             </a></li>
         </ul>
       </li>
-      <li><a href="<?cs var:toroot ?>guide/components/intents-filters.html">
+      <li class="nav-section">
-          <span class="en">Intents and Intent Filters</span>
+        <div class="nav-section-header"><a href="<?cs var:toroot ?>guide/components/intents-filters.html">
-        </a></li>
+            <span class="en">Intents and Intent Filters</span>
+          </a></div>
+        <ul>
+          <li><a href="<?cs var:toroot ?>guide/components/intents-common.html">
+            <span class="en">Common Intents</span>
+          </a></li>
+        </ul>
+      </li>
       <li><a href="<?cs var:toroot ?>guide/components/processes-and-threads.html">
           <span class="en">Processes and Threads</span>
         </a>

docs/html/guide/topics/manifest/category-element.jd

@@ -27,6 +27,14 @@ by prefixing "{@code android.intent.category.}" to the
 the string value for {@code CATEGORY_LAUNCHER} is 
 "{@code android.intent.category.LAUNCHER}".
 
+<p class="note"><strong>Note:</strong> In order to receive implicit intents, you must include the
+{@link android.content.Intent#CATEGORY_DEFAULT} category in the intent filter. The methods
+{@link android.app.Activity#startActivity startActivity()} and
+{@link android.app.Activity#startActivityForResult startActivityForResult()} treat all intents
+as if they declared the {@link android.content.Intent#CATEGORY_DEFAULT} category.
+If you do not declare it in your intent filter, no implicit intents will resolve to
+your activity.</p>
+
 <p>
 Custom categories should use the package name as a prefix, to ensure
 that they are unique.

docs/html/guide/topics/manifest/data-element.jd

@@ -5,13 +5,13 @@ parent.link=manifest-intro.html
 
 <dl class="xml">
 <dt>syntax:</dt>
-<dd><pre class="stx">&lt;data android:<a href="#host">host</a>="<i>string</i>"
+<dd><pre class="stx">&lt;data android:<a href="#scheme">scheme</a>="<i>string</i>"
-      android:<a href="#mime">mimeType</a>="<i>string</i>"
+      android:<a href="#host">host</a>="<i>string</i>"
+      android:<a href="#port">port</a>="<i>string</i>"
       android:<a href="#path">path</a>="<i>string</i>"
       android:<a href="#path">pathPattern</a>="<i>string</i>"
       android:<a href="#path">pathPrefix</a>="<i>string</i>"
-      android:<a href="#port">port</a>="<i>string</i>"
+      android:<a href="#mime">mimeType</a>="<i>string</i>" /&gt;</pre></dd>
-      android:<a href="#scheme">scheme</a>="<i>string</i>" /&gt;</pre></dd>
 
 
 <dt>contained in:</dt>
@@ -23,16 +23,17 @@ be just a data type (the <code><a href="{@docRoot}guide/topics/manifest/data-ele
 just a URI, or both a data type and a URI.  A URI is specified by separate
 attributes for each of its parts:
 
-<p style="margin-left: 2em">{@code scheme://host:port/path} <i>or</i> 
+<p style="margin-left: 2em">
-{@code pathPrefix} <i>or</i> {@code pathPattern}</p>
+{@code &lt;scheme>://&lt;host>:&lt;port>/[&lt;path>|&lt;pathPrefix>|&lt;pathPattern>]}</p>
 
 <p>
-These attributes are optional, but also mutually dependent: 
+These attributes that specify the URL format are optional, but also mutually dependent:
-If a <code><a href="{@docRoot}guide/topics/manifest/data-element.html#scheme">scheme</a></code> is not specified for the 
+<ul>
-intent filter, all the other URI attributes are ignored.  If a 
+  <li>If a <code><a href="{@docRoot}guide/topics/manifest/data-element.html#scheme">scheme</a></code>
-<code><a href="{@docRoot}guide/topics/manifest/data-element.html#host">host</a></code> is not specified for the filter, 
+is not specified for the intent filter, all the other URI attributes are ignored.</li>
-the {@code port} attribute and all the path attributes are ignored.
+  <li>If a <code><a href="{@docRoot}guide/topics/manifest/data-element.html#host">host</a></code>
-</p>
+is not specified for the filter, the {@code port} attribute and all the path attributes are ignored.
+</ul>
 
 <p>
 All the {@code &lt;data&gt;} elements contained within the same
@@ -54,7 +55,7 @@ the same filter.  So, for example, the following filter specification,
 &lt;/intent-filter&gt;</pre>
 
 <p>
-You can place any number of &lt;data&gt; elements inside an
+You can place any number of {@code &lt;data&gt;} elements inside an
 <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code> to give it multiple data
 options.  None of its attributes have default values.
 </p>
@@ -65,33 +66,51 @@ are matched against filters, can be found in another document,
 <a href="{@docRoot}guide/components/intents-filters.html">Intents and
 Intent Filters</a>.  See also the
 <a href="{@docRoot}guide/topics/manifest/manifest-intro.html#ifs">Intent Filters</a>
-section in the introduction.
+section in the manifest file overview.
 </p></dd>
 
 <dt>attributes:</dt>
 <dd><dl class="attr">
+
+<dt><a name="scheme"></a>{@code android:scheme}</dt>
+<dd>The scheme part of a URI.  This is the minimal essential attribute for
+specifying a URI; at least one {@code scheme} attribute must be set
+for the filter, or none of the other URI attributes are meaningful.
+
+<p>
+A scheme is specified without the trailing colon (for example,
+{@code http}, rather than {@code http:}).
+</p>
+
+<p>
+If the filter has a data type set (the <code><a
+href="{@docRoot}guide/topics/manifest/data-element.html#mime">mimeType</a></code>
+attribute) but no scheme, the {@code content:} and {@code file:} schemes are
+assumed.
+</p>
+
+<p class="note"><strong>Note</strong>: Scheme matching in the Android framework is
+case-sensitive, unlike the RFC.  As a result, you should always specify schemes
+using lowercase letters.</p>
+</dd>
+
 <dt><a name="host"></a>{@code android:host}</dt>
 <dd>The host part of a URI authority.  This attribute is meaningless
 unless a <code><a href="{@docRoot}guide/topics/manifest/data-element.html#scheme">scheme</a></code> attribute is also
 specified for the filter.
 
-<p class="note">Note: host name matching in the Android framework is
+<p class="note"><strong>Note</strong>: host name matching in the Android framework is
 case-sensitive, unlike the formal RFC.  As a result, you should always specify
 host names using lowercase letters.</p>
 </dd>
 
-<dt><a name="mime"></a>{@code android:mimeType}</dt>
-<dd>A MIME media type, such as {@code image/jpeg} or {@code audio/mpeg4-generic}.  
-The subtype can be the asterisk wildcard ({@code *}) to indicate that any 
-subtype matches.
 
-<p>It's common for an intent filter to declare a {@code &lt;data>} that includes
+<dt><a name="port"></a>{@code android:port}</dt>
-only the {@code android:mimeType} attribute.</p>
+<dd>The port part of a URI authority.  This attribute is meaningful only
+if the <code><a href="#scheme">scheme</a></code> and
+<code><a href="#host">host</a></code> attributes are also specified for
+the filter.</dd>
 
-<p class="note">Note: MIME type matching in the Android framework is
-case-sensitive, unlike formal RFC MIME types.  As a result, you should always
-specify MIME types using lowercase letters.</p>
-</dd>
 
 <dt><a name="path"></a>{@code android:path}
 <br/>{@code android:pathPrefix}
@@ -132,32 +151,20 @@ For more information on these three types of patterns, see the descriptions of
 attributes are also specified for the filter.
 </p></dd>
 
-<dt><a name="port"></a>{@code android:port}</dt>
+<dt><a name="mime"></a>{@code android:mimeType}</dt>
-<dd>The port part of a URI authority.  This attribute is meaningful only 
+<dd>A MIME media type, such as {@code image/jpeg} or {@code audio/mpeg4-generic}.
-if the <code><a href="#scheme">scheme</a></code> and 
+The subtype can be the asterisk wildcard ({@code *}) to indicate that any
-<code><a href="#host">host</a></code> attributes are also specified for 
+subtype matches.
-the filter.</dd>
 
-<dt><a name="scheme"></a>{@code android:scheme}</dt>
+<p>It's common for an intent filter to declare a {@code &lt;data>} that includes
-<dd>The scheme part of a URI.  This is the minimal essential attribute for 
+only the {@code android:mimeType} attribute.</p>
-specifying a URI; at least one {@code scheme} attribute must be set 
-for the filter, or none of the other URI attributes are meaningful.
 
-<p>
-A scheme is specified without the trailing colon (for example,
-{@code http}, rather than {@code http:}).
-</p>
 
-<p>
+<p class="note"><strong>Note</strong>: MIME type matching in the Android framework is
-If the filter has a data type set (the <code><a href="{@docRoot}guide/topics/manifest/data-element.html#mime">mimeType</a></code> 
+case-sensitive, unlike formal RFC MIME types.  As a result, you should always
-attribute) but no scheme, the {@code content:} and {@code file:} schemes are
+specify MIME types using lowercase letters.</p>
-assumed.
-</p>
-
-<p class="note">Note: scheme matching in the Android framework is
-case-sensitive, unlike the RFC.  As a result, you should always specify schemes
-using lowercase letters.</p>
 </dd>
+
 </dl></dd>
 
 <!-- ##api level indication## -->

docs/html/training/basics/intents/filters.jd

@@ -148,8 +148,8 @@ the recipient's address using the {@code send} or {@code sendto} URI scheme. For
 {@link android.content.Intent#CATEGORY_DEFAULT} category in the intent filter. The methods {@link
 android.app.Activity#startActivity startActivity()} and {@link
 android.app.Activity#startActivityForResult startActivityForResult()} treat all intents as if they
-contained the {@link android.content.Intent#CATEGORY_DEFAULT} category. If you do not declare it, no
+declared the {@link android.content.Intent#CATEGORY_DEFAULT} category. If you do not declare it
-implicit intents will resolve to your activity.</p>
+in your intent filter, no implicit intents will resolve to your activity.</p>
 
 <p>For more information about sending and receiving {@link android.content.Intent#ACTION_SEND}
 intents that perform social sharing behaviors, see the lesson about <a

docs/html/training/basics/intents/sending.jd

@@ -241,9 +241,13 @@ Intent intent = new Intent(Intent.ACTION_SEND);
 // Always use string resources for UI text.
 // This says something like "Share this photo with"
 String title = getResources().getString(R.string.chooser_title);
-// Create and start the chooser
+// Create intent to show chooser
 Intent chooser = Intent.createChooser(intent, title);
-startActivity(chooser);
+
+// Verify the intent will resolve to at least one activity
+if (intent.resolveActivity(getPackageManager()) != null) {
+    startActivity(chooser);
+}
 </pre>
 
 <p>This displays a dialog with a list of apps that respond to the intent passed to the {@link

docs/html/training/sharing/send.jd

@@ -75,10 +75,12 @@ startActivity(sendIntent);
 <p>If there's an installed application with a filter that matches
 {@link android.content.Intent#ACTION_SEND} and MIME type text/plain, the Android system will run
 it; if more than one application matches, the system displays a disambiguation dialog (a "chooser")
-that allows the user to choose an app. If you call
+that allows the user to choose an app.</p>
+
+<p>However, if you call
 {@link android.content.Intent#createChooser(android.content.Intent, CharSequence)
-Intent.createChooser()}
+Intent.createChooser()}, passing it your {@link android.content.Intent} object, it returns a version
-for the intent, Android will <strong>always</strong> display the chooser. This has some
+of your intent that will <strong>always display the chooser</strong>. This has some
 advantages:</p>
 
 <ul>
@@ -102,10 +104,8 @@ startActivity(<strong>Intent.createChooser(sendIntent, getResources().getText(R.
 
 <p>Optionally, you can set some standard extras for the intent:
 {@link android.content.Intent#EXTRA_EMAIL}, {@link android.content.Intent#EXTRA_CC},
-{@link android.content.Intent#EXTRA_BCC}, {@link android.content.Intent#EXTRA_SUBJECT}. However,
+{@link android.content.Intent#EXTRA_BCC}, {@link android.content.Intent#EXTRA_SUBJECT}.
-if the receiving application is not designed to use them, nothing will happen. You can use
+If the receiving application is not designed to use them, it simply ignores them.</p>
-custom extras as well, but there's no effect unless the receiving application understands them.
-Typically, you'd use custom extras defined by the receiving application itself.</p>
 
 <p class="note"><strong>Note:</strong> Some e-mail applications, such as Gmail, expect a
 {@link java.lang.String String[]} for extras like {@link android.content.Intent#EXTRA_EMAIL} and