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

    private final IIntentSender mTarget;

    /**

     * Flag for use with {@link #getActivity}, {@link #getBroadcast}, and

     * {@link #getService}: this

     * PendingIntent can only be used once.  If set, after

     * Flag indicating that this PendingIntent can be used only once.

     * For use with {@link #getActivity}, {@link #getBroadcast}, and

     * {@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

     * {@link #getService}: if the described PendingIntent already exists,

     * then simply return null instead of creating it.

     * Flag indicating that if the described PendingIntent already

     * exists, 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

     * {@link #getService}: if the described PendingIntent already exists,

     * the current one is canceled before generating a new one.  You can use

     * Flag indicating that if the described PendingIntent already exists,

     * the current one should be canceled before generating a new one.

     * 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

     */

    public static final int FLAG_CANCEL_CURRENT = 1<<28;

    /**

     * Flag for use with {@link #getActivity}, {@link #getBroadcast}, and

     * {@link #getService}: if the described PendingIntent already exists,

     * then keep it but its replace its extra data with what is in this new

     * Intent.  This can be used if you are creating intents where only the

     * Flag indicating that if the described PendingIntent already exists,

     * then keep it but replace its extra data with what is in this new

     * Intent. For use with {@link #getActivity}, {@link #getBroadcast}, and

     * {@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.

</manifest>

</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—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

some functionality where explicit intents are used to reference your service (read the blog post, <a

you publish your application, you should not change this name, because if you do, you risk breaking

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

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>Just like an activity, a service can define intent filters that allow other components to

invoke the service using implicit intents. By declaring intent filters, components

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>To ensure your app is secure, <strong>always use an explicit intent when starting or binding

your {@link android.app.Service}</strong> and do not declare intent filters for the service. If

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>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

<p>Additionally, you can ensure that your service is available to only your app by

including 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

filters.</p>

attribute and setting it to {@code "false"}. This effectively stops other apps from starting your

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>

            </a></li>

        </ul>

      </li>

      <li><a href="<?cs var:toroot ?>guide/components/intents-filters.html">

      <li class="nav-section">

        <div class="nav-section-header"><a href="<?cs var:toroot ?>guide/components/intents-filters.html">

            <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>