| page.title=Intents and Intent Filters |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>Key classes</h2> |
| <ol> |
| <li>{@link android.content.Intent}</li> |
| <li>{@link android.content.IntentFilter}</li> |
| <li>{@link android.app.Activity}</li> |
| <li>{@link android.app.Service}</li> |
| <li>{@link android.content.BroadcastReceiver}</li> |
| <li>{@link android.content.pm.PackageManager}</li> |
| </ol> |
| |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#iobjs">Intent Objects</a></li> |
| <li><a href="#ires">Intent Resolution</a></li> |
| <li style="margin-left: 2em"><a href="#ifs">Intent filters</a></li> |
| <li style="margin-left: 2em"><a href="#ccases">Common cases</a></li> |
| <li style="margin-left: 2em"><a href="#imatch">Using intent matching</a></li> |
| <li><a href="#npex">Note Pad Example</a></li> |
| </ol> |
| </div> |
| </div> |
| |
| |
| <p> |
| Three of the core components of an application — activities, services, and |
| broadcast receivers — are activated through messages, called <i>intents</i>. |
| Intent messaging is a facility for late run-time binding between components in the same |
| or different applications. The intent itself, an {@link android.content.Intent} |
| object, is a passive data structure holding an abstract description of an operation |
| to be performed — or, often in the case of broadcasts, a description of something |
| that has happened and is being announced. There are separate mechanisms for |
| delivering intents to each type of component: |
| </p> |
| |
| <ul> |
| <li>An Intent object is passed to <code>{@link android.content.Context#startActivity |
| Context.startActivity()}</code> or <code>{@link android.app.Activity#startActivityForResult |
| Activity.startActivityForResult()}</code> to launch an activity or get an existing |
| activity to do something new. (It can also be passed to |
| <code>{@link android.app.Activity#setResult(int, Intent) Activity.setResult()}</code> |
| to return information to the activity that called {@code startActivityForResult()}.)</li> |
| |
| <li><p>An Intent object is passed to <code>{@link android.content.Context#startService |
| Context.startService()}</code> to initiate a service or deliver new instructions to an |
| ongoing service. Similarly, an intent can be passed to <code>{@link |
| android.content.Context#bindService Context.bindService()}</code> to establish a |
| connection between the calling component and a target service. It can optionally |
| initiate the service if it's not already running.</p></li> |
| |
| <li><p>Intent objects passed to any of the broadcast methods (such as <code>{@link |
| android.content.Context#sendBroadcast(Intent) Context.sendBroadcast()}</code>, |
| <code>{@link android.content.Context#sendOrderedBroadcast(Intent, String) |
| Context.sendOrderedBroadcast()}</code>, or <code>{@link |
| android.content.Context#sendStickyBroadcast Context.sendStickyBroadcast()}</code>) |
| are delivered to all interested broadcast receivers. Many kinds of broadcasts |
| originate in system code.</p></li> |
| </ul> |
| |
| <p> |
| In each case, the Android system finds the appropriate activity, service, or set |
| of broadcast receivers to respond to the intent, instantiating them if necessary. |
| There is no overlap within these messaging systems: Broadcast intents are delivered |
| only to broadcast receivers, never to activities or services. An intent passed to |
| {@code startActivity()} is delivered only to an activity, never to a service or |
| broadcast receiver, and so on. |
| </p> |
| |
| <p> |
| This document begins with a description of Intent objects. It then describes the |
| rules Android uses to map intents to components — how it resolves which |
| component should receive an intent message. For intents that don't explicitly |
| name a target component, this process involves testing the Intent object against |
| <i>intent filters</i> associated with potential targets. |
| </p> |
| |
| |
| <h2><a name="iobjs"></a>Intent Objects</h2> |
| |
| <p> |
| An {@link android.content.Intent} object is a bundle of information. It |
| contains information of interest to the component that receives the intent |
| (such as the action to be taken and the data to act on) plus information |
| of interest to the Android system (such as the category of component that |
| should handle the intent and instructions on how to launch a target activity). |
| Principally, it can contain the following: |
| </p> |
| |
| <dl> |
| |
| <dt><b>Component name</b><a name="cname"></a></dt> |
| <dd>The name of the component that should handle the intent. This field is |
| a {@link android.content.ComponentName} object — a combination of the |
| fully qualified class name of the target component (for example "{@code |
| com.example.project.app.FreneticActivity}") and the package name set |
| in the manifest file of the application where the component resides (for |
| example, "{@code com.example.project}"). The package part of the component |
| name and the package name set in the manifest do not necessarily have to match. |
| |
| <p> |
| The component name is optional. If it is set, the Intent object is |
| delivered to an instance of the designated class. If it is not set, |
| Android uses other information in the Intent object to locate a suitable |
| target — see <a href="#ires">Intent Resolution</a>, later in this |
| document. |
| </p> |
| |
| <p> |
| The component name is set by <code>{@link android.content.Intent#setComponent |
| setComponent()}</code>, <code>{@link android.content.Intent#setClass |
| setClass()}</code>, or <code>{@link android.content.Intent#setClassName(String, String) |
| setClassName()}</code> and read by <code>{@link android.content.Intent#getComponent |
| getComponent()}</code>. |
| </p> |
| </dd> |
| |
| <p><dt><b>Action</b></dt> |
| <dd>A string naming the action to be performed — or, in the case of broadcast |
| intents, the action that took place and is being reported. The Intent class defines |
| a number of action constants, including these: |
| </p> |
| |
| <table> |
| <tr> |
| <th>Constant</th> |
| <th>Target component</th> |
| <th>Action</th> |
| </tr><tr> |
| <td>{@code ACTION_CALL} |
| <td>activity |
| <td>Initiate a phone call. |
| </tr><tr> |
| <td>{@code ACTION_EDIT} |
| <td>activity |
| <td>Display data for the user to edit. |
| </tr><tr> |
| <td>{@code ACTION_MAIN} |
| <td>activity |
| <td>Start up as the initial activity of a task, with no data input and no returned output. |
| </tr><tr> |
| <td>{@code ACTION_SYNC} |
| <td>activity |
| <td>Synchronize data on a server with data on the mobile device. |
| </tr><tr> |
| <td>{@code ACTION_BATTERY_LOW} |
| <td>broadcast receiver |
| <td>A warning that the battery is low. |
| </tr><tr> |
| <td>{@code ACTION_HEADSET_PLUG} |
| <td>broadcast receiver |
| <td>A headset has been plugged into the device, or unplugged from it. |
| </tr><tr> |
| <td>{@code ACTION_SCREEN_ON} |
| <td>broadcast receiver |
| <td>The screen has been turned on. |
| </tr><tr> |
| <td>{@code ACTION_TIMEZONE_CHANGED} |
| <td>broadcast receiver |
| <td>The setting for the time zone has changed. |
| </tr> |
| </table> |
| |
| <p> |
| See the {@link android.content.Intent} class description for a list of |
| pre-defined constants for generic actions. Other actions are defined |
| elsewhere in the Android API. |
| You can also define your own action strings for activating the components |
| in your application. Those you invent should include the application |
| package as a prefix — for example: |
| "<code>com.example.project.SHOW_COLOR</code>". |
| </p> |
| |
| <p> |
| The action largely determines how the rest of the intent is structured |
| — particularly the <a href="#data">data</a> and |
| <a href="#extras">extras</a> fields — |
| much as a method name determines a set of arguments and a return value. |
| For this reason, it's a good idea to use action names that are |
| as specific as possible, and to couple them tightly to the other fields of |
| the intent. In other words, instead of defining an action in isolation, |
| define an entire protocol for the Intent objects your components can handle. |
| </p> |
| |
| <p> |
| The action in an Intent object is set by the |
| <code>{@link android.content.Intent#setAction setAction()}</code> |
| method and read by |
| <code>{@link android.content.Intent#getAction getAction()}</code>. |
| </p> |
| </dd> |
| |
| <p><dt><b>Data</b><a name="data"></a></dt> |
| <dd>The URI of the data to be acted on and the MIME type of that data. Different |
| actions are paired with different kinds of data specifications. For example, if |
| the action field is {@code ACTION_EDIT}, |
| the data field would contain the URI of the document to be displayed for editing. |
| If the action is {@code ACTION_CALL}, the data field would be a {@code tel:} URI |
| with the number to call. Similarly, if the action is {@code ACTION_VIEW} and the |
| data field is an {@code http:} URI, the receiving activity would be called upon |
| to download and display whatever data the URI refers to. |
| |
| <p> |
| When matching an intent to a component that is capable of handling the data, |
| it's often important to know the type of data (its MIME type) in addition to its URI. |
| For example, a component able to display image data should not be called |
| upon to play an audio file. |
| </p> |
| |
| <p> |
| In many cases, the data type can be inferred from the URI — particularly |
| {@code content:} URIs, which indicate that the data is located on the device and |
| controlled by a content provider (see the |
| <a href="{@docRoot}guide/topics/providers/content-providers.html">separate |
| discussion on content providers</a>). But the type can also be explicitly set |
| in the Intent object. |
| The <code>{@link android.content.Intent#setData setData()}</code> method specifies |
| data only as a URI, <code>{@link android.content.Intent#setType setType()}</code> |
| specifies it only as a MIME type, and <code>{@link |
| android.content.Intent#setDataAndType setDataAndType()}</code> specifies it as both |
| a URI and a MIME type. The URI is read by <code>{@link |
| android.content.Intent#getData getData()}</code> and the type by <code>{@link |
| android.content.Intent#getType getType()}</code>. |
| </p> |
| </dd> |
| |
| <p><dt><b>Category</b></dt> |
| <dd>A string containing additional information about the kind of component |
| that should handle the intent. Any number of category descriptions can be |
| placed in an Intent object. As it does for actions, the Intent class defines |
| several category constants, including these: |
| |
| <table> |
| <tr> |
| <th>Constant</th> |
| <th>Meaning</th> |
| </tr><tr> |
| <td>{@code CATEGORY_BROWSABLE} |
| <td>The target activity can be safely invoked by the browser to display data |
| referenced by a link — for example, an image or an e-mail message. |
| </tr><tr> |
| <td>{@code CATEGORY_GADGET} |
| <td>The activity can be embedded inside of another activity that hosts gadgets. |
| </tr><tr> |
| <td>{@code CATEGORY_HOME} |
| <td>The activity displays the home screen, the first screen the user sees when |
| the device is turned on or when the HOME key is pressed. |
| </tr><tr> |
| <td>{@code CATEGORY_LAUNCHER} |
| <td>The activity can be the initial activity of a task and is listed in |
| the top-level application launcher. |
| </tr><tr> |
| <td>{@code CATEGORY_PREFERENCE} |
| <td>The target activity is a preference panel. |
| </tr> |
| </table> |
| |
| <p> |
| See the {@link android.content.Intent} class description for the full list of |
| categories. |
| </p> |
| |
| <p> |
| The <code>{@link android.content.Intent#addCategory addCategory()}</code> method |
| places a category in an Intent object, <code>{@link android.content.Intent#removeCategory |
| removeCategory()}</code> deletes a category previously added, and <code>{@link android.content.Intent#getCategories getCategories()}</code> gets the set of all |
| categories currently in the object. |
| </p> |
| </dd> |
| |
| <p><dt><b>Extras</b><a name="extras"></a></dt> |
| <dd>Key-value pairs for additional information that should be delivered to the |
| component handling the intent. Just as some actions are paired with particular |
| kinds of data URIs, some are paired with particular extras. For example, an |
| {@code ACTION_TIMEZONE_CHANGED} intent has a "{@code time-zone}" extra that |
| identifies the new time zone, and {@code ACTION_HEADSET_PLUG} has a |
| "{@code state}" extra indicating whether the headset is now plugged in or |
| unplugged, as well as a "{@code name}" extra for the type of headset. |
| If you were to invent a {@code SHOW_COLOR} action, the color value would |
| be set in an extra key-value pair. |
| |
| <p> |
| The Intent object has a series of {@code put...()} methods for inserting various |
| types of extra data and a similar set of {@code get...()} methods for reading |
| the data. These methods parallel those for {@link android.os.Bundle} objects. |
| In fact, the extras can be installed and read as a Bundle using the <code>{@link |
| android.content.Intent#putExtras putExtras()}</code> and <code>{@link |
| android.content.Intent#getExtras getExtras()}</code> methods. |
| </p> |
| </dd> |
| |
| <p><dt><b>Flags</b></dt> |
| <dd>Flags of various sorts. Many instruct the Android system how to launch an |
| activity (for example, which task the activity should belong to) and how to treat |
| it after it's launched (for example, whether it belongs in the list of recent |
| activities). All these flags are defined in the Intent class. |
| </dd> |
| |
| </dl> |
| |
| <p> |
| The Android system and the applications that come with the platform employ |
| Intent objects both to send out system-originated broadcasts and to activate |
| system-defined components. To see how to structure an intent to activate a |
| system component, consult the |
| <a href="{@docRoot}guide/appendix/g-app-intents.html">list of intents</a> |
| in the reference. |
| </p> |
| |
| |
| <h2><a name="ires"></a>Intent Resolution</h2> |
| |
| <p> |
| Intents can be divided into two groups: |
| </p> |
| |
| <ul> |
| <li><i>Explicit intents</i> designate the target component by its |
| name (the <a href="#cname">component name field</a>, mentioned earlier, |
| has a value set). Since component names would generally not be known to |
| developers of other applications, explicit intents are typically used |
| for application-internal messages — such as an activity starting |
| a subordinate service or launching a sister activity.</li> |
| |
| <li><p><i>Implicit intents</i> do not name a target (the field for |
| the component name is blank). Implicit intents are often used to |
| activate components in other applications.</p></li> |
| </ul> |
| |
| <p> |
| Android delivers an explicit intent to an instance of the designated |
| target class. Nothing in the Intent object other than the component |
| name matters for determining which component should get the intent. |
| </p> |
| |
| <p> |
| A different strategy is needed for implicit intents. In the absence of a |
| designated target, the Android system must find the best component (or |
| components) to handle the intent — a single activity or service to |
| perform the requested action or the set of broadcast receivers to respond |
| to the broadcast announcement. It does so by comparing the contents of |
| the Intent object to <i>intent filters</i>, structures associated with |
| components that can potentially receive intents. Filters advertise the |
| capabilities of a component and delimit the intents it can handle. They |
| open the component to the possibility of receiving implicit intents of |
| the advertised type. If a component does not have any intent filters, |
| it can receive only explicit intents. A component with filters can |
| receive both explicit and implicit intents. |
| </p> |
| |
| <p> |
| Only three aspects of an Intent object are consulted when the object |
| is tested against an intent filter: |
| </p> |
| |
| <p style="margin-left: 2em">action |
| <br/>data (both URI and data type) |
| <br/>category</p> |
| |
| <p> |
| The extras and flags play no part in resolving which component receives |
| an intent. |
| </p> |
| |
| |
| <h3><a name="ifs"></a>Intent filters</h3> |
| |
| <p> |
| To inform the system which implicit intents they can handle, activities, |
| services, and broadcast receivers can have one or more intent filters. |
| Each filter describes a capability of the component, a set of intents that |
| the component is willing to receive. It, in effect, filters in |
| intents of a desired type, while filtering out unwanted |
| intents — but only unwanted implicit intents (those that don't name |
| a target class). An explicit intent is always delivered to its target, |
| no matter what it contains; the filter is not consulted. But an implicit |
| intent is delivered to a component only if it can pass through one of the |
| component's filters. |
| </p> |
| |
| <p> |
| A component has separate filters for each job it can do, each face it can |
| present to the user. For example, the NoteEditor activity of the sample |
| Note Pad application has two filters — one for starting up with a |
| specific note that the user can view or edit, and another for starting |
| with a new, blank note that the user can fill in and save. (All of Note |
| Pad's filters are described in the <a href="#npex">Note Pad Example</a> |
| section, later.) |
| </p> |
| |
| <div class="sidebox-wrapper"> |
| <div class="sidebox-inner"> |
| <h2>Filters and security</h2> |
| <p>An intent filter cannot be relied on for security. While it opens a |
| component to receiving only certain kinds of implicit intents, it does |
| nothing to prevent explicit intents from targeting the component. Even |
| though a filter restricts the intents a component will be asked to handle |
| to certain actions and data sources, someone could always put |
| together an explicit intent with a different action and data source, and |
| name the component as the target. |
| </p> |
| </div> |
| </div> |
| |
| <p> |
| An intent filter is an instance of the {@link android.content.IntentFilter} class. |
| However, since the Android system must know about the capabilities of a component |
| before it can launch that component, intent filters are generally not set up in |
| Java code, but in the application's manifest file (AndroidManifest.xml) as |
| <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> |
| elements. (The one exception would be filters for |
| broadcast receivers that are registered dynamically by calling <code>{@link android.content.Context#registerReceiver(BroadcastReceiver, IntentFilter, String, |
| Handler) Context.registerReceiver()}</code>; they are directly created as |
| IntentFilter objects.) |
| </p> |
| |
| <p> |
| A filter has fields that parallel the action, data, and category fields of an |
| Intent object. An implicit intent is tested against the filter in all three areas. |
| To be delivered to the component that owns the filter, it must pass all three tests. |
| If it fails even one of them, the Android system won't deliver it to the |
| component — at least not on the basis of that filter. However, since a |
| component can have multiple intent filters, an intent that does not pass |
| through one of a component's filters might make it through on another. |
| </p> |
| |
| <p> |
| Each of the three tests is described in detail below: |
| </p> |
| |
| <dl> |
| |
| <dt><b>Action test</b></dt> |
| <dd>An |
| <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> |
| element in the manifest file lists actions as |
| <code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code> |
| subelements. For example: |
| |
| <pre><intent-filter . . . > |
| <action android:name="com.example.project.SHOW_CURRENT" /> |
| <action android:name="com.example.project.SHOW_RECENT" /> |
| <action android:name="com.example.project.SHOW_PENDING" /> |
| . . . |
| </intent-filter></pre> |
| |
| <p> |
| As the example shows, while an Intent object names just a single action, |
| a filter may list more than one. The list cannot be empty; a filter must |
| contain at least one {@code <action>} element, or it |
| will block all intents. |
| </p> |
| |
| <p> |
| To pass this test, the action specified in the Intent object must match |
| one of the actions listed in the filter. If the object or the filter |
| does not specify an action, the results are as follows: |
| </p> |
| |
| <ul> |
| <li>If the filter fails to list any actions, there is nothing for an |
| intent to match, so all intents fail the test. No intents can get |
| through the filter.</li> |
| |
| <li><p>On the other hand, an Intent object that doesn't specify an |
| action automatically passes the test — as long as the filter |
| contains at least one action.</p></li> |
| </ul |
| </dd> |
| |
| <dt><b>Category test</b></dt> |
| <dd>An |
| <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> |
| element also lists categories as subelements. For example: |
| |
| <pre><intent-filter . . . > |
| <category android:name="android.intent.category.DEFAULT" /> |
| <category android:name="android.intent.category.BROWSABLE" /> |
| . . . |
| </intent-filter></pre> |
| |
| <p> |
| Note that the constants described earlier for actions and categories are not |
| used in the manifest file. The full string values are used instead. For |
| instance, the "{@code android.intent.category.BROWSABLE}" string in the example |
| above corresponds to the {@code CATEGORY_BROWSABLE} constant mentioned earlier |
| in this document. Similarly, the string "{@code android.intent.action.EDIT}" |
| corresponds to the {@code ACTION_EDIT} constant. |
| </p> |
| |
| <p> |
| For an intent to pass the category test, every category in the Intent object |
| must match a category in the filter. The filter can list additional categories, |
| but it cannot omit any that are in the intent. |
| </p> |
| |
| <p> |
| In principle, therefore, an Intent object with no categories should always pass |
| this test, regardless of what's in the filter. That's mostly true. However, |
| with one exception, Android treats all implicit intents passed to {@link |
| android.content.Context#startActivity startActivity()} as if they contained |
| at least one category: "{@code android.intent.category.DEFAULT}" (the |
| {@code CATEGORY_DEFAULT} constant). |
| Therefore, activities that are willing to receive implicit intents must |
| include "{@code android.intent.category.DEFAULT}" in their intent filters. |
| (Filters with "{@code android.intent.action.MAIN}" and |
| "{@code android.intent.category.LAUNCHER}" settings are the exception. |
| They mark activities that begin new tasks and that are represented on the |
| launcher screen. They can include "{@code android.intent.category.DEFAULT}" |
| in the list of categories, but don't need to.) See <a href="#imatch">Using |
| intent matching</a>, later, for more on these filters.) |
| </p> |
| <dd> |
| |
| <dt><b>Data test</b></dt> |
| <dd>Like the action and categories, the data specification for an intent filter |
| is contained in a subelement. And, as in those cases, the subelement can appear |
| multiple times, or not at all. For example: |
| |
| <pre><intent-filter . . . > |
| <data android:mimeType="video/mpeg" android:scheme="http" . . . /> |
| <data android:mimeType="audio/mpeg" android:scheme="http" . . . /> |
| . . . |
| </intent-filter></pre> |
| |
| <p> |
| Each |
| <code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> |
| element can specify a URI and a data type (MIME media type). There are separate |
| attributes — {@code scheme}, {@code host}, {@code port}, |
| and {@code path} — for each part of the URI: |
| </p> |
| |
| <p style="margin-left: 2em">{@code scheme://host:port/path}</p> |
| |
| <p> |
| For example, in the following URI, |
| </p> |
| |
| <p style="margin-left: 2em">{@code content://com.example.project:200/folder/subfolder/etc}</p> |
| |
| <p> the scheme is "{@code content}", the host is "{@code com.example.project}", |
| the port is "{@code 200}", and the path is "{@code folder/subfolder/etc}". |
| The host and port together constitute the URI <i>authority</i>; if a host is |
| not specified, the port is ignored. |
| </p> |
| |
| <p> |
| Each of these attributes is optional, but they are not independent of each other: |
| For an authority to be meaningful, a scheme must also be specified. |
| For a path to be meaningful, both a scheme and an authority must be specified. |
| </p> |
| |
| <p> |
| When the URI in an Intent object is compared to a URI specification in a filter, |
| it's compared only to the parts of the URI actually mentioned in the filter. |
| For example, if a filter specifies only a scheme, all URIs with that scheme match |
| the filter. If a filter specifies a scheme and an authority but no path, all URIs |
| with the same scheme and authority match, regardless of their paths. If a filter |
| specifies a scheme, an authority, and a path, only URIs with the same scheme, |
| authority, and path match. However, a path specification in the filter can |
| contain wildcards to require only a partial match of the path. |
| </p> |
| |
| <p> |
| The {@code type} attribute of a {@code <data>} element specifies the MIME type |
| of the data. It's more common in filters than a URI. Both the Intent object and |
| the filter can use a "*" wildcard for the subtype field — for example, |
| "{@code text/*}" or "{@code audio/*}" — indicating any subtype matches. |
| </p> |
| |
| <p> |
| The data test compares both the URI and the data type in the Intent object to a URI |
| and data type specified in the filter. The rules are as follows: |
| </p> |
| |
| <ol type="a"> |
| <li>An Intent object that contains neither a URI nor a data type passes the |
| test only if the filter likewise does not specify any URIs or data types.</li> |
| |
| <li><p>An Intent object that contains a URI but no data type (and a type cannot |
| be inferred from the URI) passes the test only if its URI matches a URI in the |
| filter and the filter likewise does not specify a type. This will be the case |
| only for URIs like {@code mailto:} and {@code tel:} that do not refer to actual data.</p></li> |
| |
| <li><p>An Intent object that contains a data type but not a URI passes the test |
| only if the filter lists the same data type and similarly does not specify a URI.</p></li> |
| |
| <li><p>An Intent object that contains both a URI and a data type (or a data type |
| can be inferred from the URI) passes the data type part of the test only if its |
| type matches a type listed in the filter. It passes the URI part of the test |
| either if its URI matches a URI in the filter or if it has a {@code content:} |
| or {@code file:} URI and the filter does not specify a URI. In other words, |
| a component is presumed to support {@code content:} and {@code file:} data if |
| its filter lists only a data type.</p></li> |
| </ol> |
| </dl> |
| |
| <p> |
| If an intent can pass through the filters of more than one activity or service, |
| the user may be asked which component to activate. An exception is raised if |
| no target can be found. |
| </p> |
| |
| |
| <h3><a name="ccases"></a>Common cases</h3> |
| |
| <p> |
| The last rule shown above for the data test, rule (d), reflects the expectation |
| that components are able to get local data from a file or content provider. |
| Therefore, their filters can list just a data type and do not need to explicitly |
| name the {@code content:} and {@code file:} schemes. |
| This is a typical case. A {@code <data>} element like the following, |
| for example, tells Android that the component can get image data from a content |
| provider and display it: |
| </p> |
| |
| <pre><data android:mimeType="image/*" /></pre> |
| |
| <p> |
| Since most available data is dispensed by content providers, filters that |
| specify a data type but not a URI are perhaps the most common. |
| </p> |
| |
| <p> |
| Another common configuration is filters with a scheme and a data type. For |
| example, a {@code <data>} element like the following tells Android that |
| the component can get video data from the network and display it: |
| </p> |
| |
| <pre><data android:scheme="http" android:type="video/*" /></pre> |
| |
| <p> |
| Consider, for example, what the browser application does when |
| the user follows a link on a web page. It first tries to display the data |
| (as it could if the link was to an HTML page). If it can't display the data, |
| it puts together an implicit intent with the scheme and data type and tries |
| to start an activity that can do the job. If there are no takers, it asks the |
| download manager to download the data. That puts it under the control |
| of a content provider, so a potentially larger pool of activities |
| (those with filters that just name a data type) can respond. |
| </p> |
| |
| <p> |
| Most applications also have a way to start fresh, without a reference |
| to any particular data. Activities that can initiate applications |
| have filters with "{@code android.intent.action.MAIN}" specified as |
| the action. If they are to be represented in the application launcher, |
| they also specify the "{@code android.intent.category.LAUNCHER}" |
| category: |
| </p> |
| |
| <pre><intent-filter . . . > |
| <action android:name="code android.intent.action.MAIN" /> |
| <category android:name="code android.intent.category.LAUNCHER" /> |
| </intent-filter></pre> |
| |
| |
| <h3><a name="imatch"></a>Using intent matching</h3> |
| |
| <p> |
| Intents are matched against intent filters not only to discover a target |
| component to activate, but also to discover something about the set of |
| components on the device. For example, the Android system populates the |
| application launcher, the top-level screen that shows the applications |
| that are available for the user to launch, by finding all the activities |
| with intent filters that specify the "{@code android.intent.action.MAIN}" |
| action and "{@code android.intent.category.LAUNCHER}" category |
| (as illustrated in the previous section). It then displays the icons and |
| labels of those activities in the launcher. Similarly, it discovers the |
| home screen by looking for the activity with |
| "{@code android.intent.category.HOME}" in its filter. |
| </p> |
| |
| <p> |
| Your application can use intent matching is a similar way. |
| The {@link android.content.pm.PackageManager} has a set of {@code query...()} |
| methods that return all components that can accept a particular intent, and |
| a similar series of {@code resolve...()} methods that determine the best |
| component to respond to an intent. For example, |
| {@link android.content.pm.PackageManager#queryIntentActivities |
| queryIntentActivities()} returns a list of all activities that can perform |
| the intent passed as an argument, and {@link |
| android.content.pm.PackageManager#queryIntentServices |
| queryIntentServices()} returns a similar list of services. |
| Neither method activates the components; they just list the ones that |
| can respond. There's a similar method, |
| {@link android.content.pm.PackageManager#queryBroadcastReceivers |
| queryBroadcastReceivers()}, for broadcast receivers. |
| </p> |
| |
| <h2 id="npex">Note Pad Example</h2> |
| |
| <p> |
| The Note Pad sample application enables users to browse through a list |
| of notes, view details about individual items in the list, edit the items, |
| and add a new item to the list. This section looks at the intent filters |
| declared in its manifest file. (If you're working offline in the SDK, you |
| can find all the source files for this sample application, including its |
| manifest file, at {@code <sdk>/samples/NotePad/index.html}. |
| If you're viewing the documentation online, the source files are in the |
| <a href="{@docRoot}guide/samples/index.html">Tutorials and Sample Code</a> |
| section <a href="{@docRoot}guide/samples/NotePad/index.html">here</a>.) |
| </p> |
| |
| <p> |
| In its manifest file, the Note Pad application declares three activities, |
| each with at least one intent filter. It also declares a content provider |
| that manages the note data. Here is the manifest file in its entirety: |
| </p> |
| |
| <pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" |
| package="com.example.android.notepad"> |
| <application android:icon="@drawable/app_notes" |
| android:label="@string/app_name" > |
| |
| <provider android:name="NotePadProvider" |
| android:authorities="com.google.provider.NotePad" /> |
| |
| <activity android:name="NotesList" android:label="@string/title_notes_list"> |
| <intent-filter> |
| <action android:name="android.intent.action.MAIN" /> |
| <category android:name="android.intent.category.LAUNCHER" /> |
| </intent-filter> |
| <intent-filter> |
| <action android:name="android.intent.action.VIEW" /> |
| <action android:name="android.intent.action.EDIT" /> |
| <action android:name="android.intent.action.PICK" /> |
| <category android:name="android.intent.category.DEFAULT" /> |
| <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> |
| </intent-filter> |
| <intent-filter> |
| <action android:name="android.intent.action.GET_CONTENT" /> |
| <category android:name="android.intent.category.DEFAULT" /> |
| <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> |
| </intent-filter> |
| </activity> |
| |
| <activity android:name="NoteEditor" |
| android:theme="@android:style/Theme.Light" |
| android:label="@string/title_note" > |
| <intent-filter android:label="@string/resolve_edit"> |
| <action android:name="android.intent.action.VIEW" /> |
| <action android:name="android.intent.action.EDIT" /> |
| <action android:name="com.android.notepad.action.EDIT_NOTE" /> |
| <category android:name="android.intent.category.DEFAULT" /> |
| <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> |
| </intent-filter> |
| <intent-filter> |
| <action android:name="android.intent.action.INSERT" /> |
| <category android:name="android.intent.category.DEFAULT" /> |
| <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> |
| </intent-filter> |
| </activity> |
| |
| <activity android:name="TitleEditor" |
| android:label="@string/title_edit_title" |
| android:theme="@android:style/Theme.Dialog"> |
| <intent-filter android:label="@string/resolve_title"> |
| <action android:name="com.android.notepad.action.EDIT_TITLE" /> |
| <category android:name="android.intent.category.DEFAULT" /> |
| <category android:name="android.intent.category.ALTERNATIVE" /> |
| <category android:name="android.intent.category.SELECTED_ALTERNATIVE" /> |
| <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> |
| </intent-filter> |
| </activity> |
| |
| </application> |
| </manifest></pre> |
| |
| <p> |
| The first activity, NotesList, is |
| distinguished from the other activities by the fact that it operates |
| on a directory of notes (the note list) rather than on a single note. |
| It would generally serve as the initial user interface into the |
| application. It can do three things as described by its three intent |
| filters: |
| </p> |
| |
| <ol> |
| <li><pre><intent-filter> |
| <action android:name="android.intent.action.MAIN" /> |
| <category android:name="android.intent.category.LAUNCHER" /> |
| </intent-filter></pre> |
| |
| <p> |
| This filter declares the main entry point into the Note Pad application. |
| The standard {@code MAIN} action is an entry point that does not require |
| any other information in the Intent (no data specification, for example), |
| and the {@code LAUNCHER} category says that this entry point should be |
| listed in the application launcher. |
| </p></li> |
| |
| <li><pre><intent-filter> |
| <action android:name="android.intent.action.VIEW" /> |
| <action android:name="android.intent.action.EDIT" /> |
| <action android:name="android.intent.action.PICK" /> |
| <category android:name="android.intent.category.DEFAULT" /> |
| <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> |
| </intent-filter></pre> |
| |
| <p> |
| This filter declares the things that the activity can do on a directory |
| of notes. It can allow the user to view or edit the directory (via |
| the {@code VIEW} and {@code EDIT} actions), or to pick a particular note |
| from the directory (via the {@code PICK} action). |
| </p> |
| |
| <p> |
| The {@code mimeType} attribute of the |
| <code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> |
| element specifies the kind of data that these actions operate on. It |
| indicates that the activity can get a Cursor over zero or more items |
| ({@code vnd.android.cursor.dir}) from a content provider that holds |
| Note Pad data ({@code vnd.google.note}). The Intent object that launches |
| the activity would include a {@code content:} URI specifying the exact |
| data of this type that the activity should open. |
| </p> |
| |
| <p> |
| Note also the {@code DEFAULT} category supplied in this filter. It's |
| there because the <code>{@link android.content.Context#startActivity |
| Context.startActivity()}</code> and |
| <code>{@link android.app.Activity#startActivityForResult |
| Activity.startActivityForResult()}</code> methods treat all intents |
| as if they contained the {@code DEFAULT} category — with just |
| two exceptions: |
| </p> |
| |
| <ul> |
| <li>Intents that explicitly name the target activity</li> |
| <li>Intents consisting of the {@code MAIN} action and {@code LAUNCHER} |
| category</li> |
| </ul> |
| |
| <p> |
| Therefore, the {@code DEFAULT} category is <em>required</em> for all |
| filters — except for those with the {@code MAIN} action and |
| {@code LAUNCHER} category. (Intent filters are not consulted for |
| explicit intents.) |
| </p></li> |
| |
| <li><pre><intent-filter> |
| <action android:name="android.intent.action.GET_CONTENT" /> |
| <category android:name="android.intent.category.DEFAULT" /> |
| <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> |
| </intent-filter></pre> |
| |
| <p> |
| This filter describes the activity's ability to return a note selected by |
| the user without requiring any specification of the directory the user should |
| choose from. The {@code GET_CONTENT} action is similar to the {@code PICK} |
| action. In both cases, the activity returns the URI for a note selected by |
| the user. (In each case, it's returned to the activity that called |
| <code>{@link android.app.Activity#startActivityForResult |
| startActivityForResult()}</code> to start the NoteList activity.) Here, |
| however, the caller specifies the type of data desired instead of the |
| directory of data the user will be picking from. |
| </p> |
| |
| <p> |
| The data type, <code>vnd.android.cursor.item/vnd.google.note</code>, |
| indicates the type of data the activity can return — a URI for |
| a single note. From the returned URI, the caller can get a Cursor for |
| exactly one item ({@code vnd.android.cursor.item}) from the content |
| provider that holds Note Pad data ({@code vnd.google.note}). |
| </p> |
| |
| <p> |
| In other words, for the {@code PICK} action in the previous filter, |
| the data type indicates the type of data the activity could display to the |
| user. For the {@code GET_CONTENT} filter, it indicates the type of data |
| the activity can return to the caller. |
| </p></li> |
| </ol> |
| |
| <p> |
| Given these capabilities, the following intents will resolve to the |
| NotesList activity: |
| </p> |
| |
| <dl style="margin-left: 2em"> |
| <dt>action: <code>android.intent.action.MAIN</code></dt> |
| <dd>Launches the activity with no data specified.</dd> |
| |
| <dt>action: <code>android.intent.action.MAIN</code> |
| <br/>category: <code>android.intent.category.LAUNCHER</code></dt> |
| <dd> Launches the activity with no data selected specified. |
| This is the actual intent used by the Launcher to populate its top-level |
| list. All activities with filters that match this action and category |
| are added to the list.</dd> |
| |
| <dt>action: <code>android.intent.action.VIEW</code> |
| <br/>data: <code>content://com.google.provider.NotePad/notes</code></dt> |
| <dd>Asks the activity to display a list of all the notes under |
| <code>content://com.google.provider.NotePad/notes</code>. The user can then |
| browse through the list and get information about the items in it.</dd> |
| |
| <dt>action: <code>android.intent.action.PICK</code> |
| <br/>data: <code>content://com.google.provider.NotePad/notes</code></dt> |
| <dd>Asks the activity to display a list of the notes under |
| <code>content://com.google.provider.NotePad/notes</code>. |
| The user can then pick a note from the list, and the activity will return |
| the URI for that item back to the activity that started the NoteList activity.</dd> |
| |
| <dt>action: <code>android.intent.action.GET_CONTENT</code> |
| <br/>data type: <code>vnd.android.cursor.item/vnd.google.note</code></dt> |
| <dd>Asks the activity to supply a single item of Note Pad data.</dd> |
| </dl> |
| |
| <p> |
| The second activity, NoteEditor, shows |
| users a single note entry and allows them to edit it. It can do two things |
| as described by its two intent filters: |
| |
| <ol> |
| <li><pre><intent-filter android:label="@string/resolve_edit"> |
| <action android:name="android.intent.action.VIEW" /> |
| <action android:name="android.intent.action.EDIT" /> |
| <action android:name="com.android.notepad.action.EDIT_NOTE" /> |
| <category android:name="android.intent.category.DEFAULT" /> |
| <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> |
| </intent-filter></pre> |
| |
| <p> |
| The first, primary, purpose of this activity is to enable the user to |
| interact with a single note &mdash to either {@code VIEW} the note or |
| {@code EDIT} it. (The {@code EDIT_NOTE} category is a synonym for |
| {@code EDIT}.) The intent would contain the URI for data matching the |
| MIME type <code>vnd.android.cursor.item/vnd.google.note</code> — |
| that is, the URI for a single, specific note. It would typically be a |
| URI that was returned by the {@code PICK} or {@code GET_CONTENT} |
| actions of the NoteList activity. |
| </p> |
| |
| <p> |
| As before, this filter lists the {@code DEFAULT} category so that the |
| activity can be launched by intents that don't explicitly specify the |
| NoteEditor class. |
| </p></li> |
| |
| <li><pre><intent-filter> |
| <action android:name="android.intent.action.INSERT" /> |
| <category android:name="android.intent.category.DEFAULT" /> |
| <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> |
| </intent-filter></pre> |
| |
| <p> |
| The secondary purpose of this activity is to enable the user to create a new |
| note, which it will {@code INSERT} into an existing directory of notes. The |
| intent would contain the URI for data matching the MIME type |
| <code>vnd.android.cursor.dir/vnd.google.note</code> — that |
| is, the URI for the directory where the note should be placed. |
| </p></li> |
| </ol> |
| |
| <p> |
| Given these capabilities, the following intents will resolve to the |
| NoteEditor activity: |
| </p> |
| |
| <dl style:"margin-left: 2em"> |
| <dt>action: <code>android.intent.action.VIEW</code> |
| <br/>data: <code>content://com.google.provider.NotePad/notes/<var>ID</var></code></dt> |
| <dd>Asks the activity to display the content of the note identified |
| by {@code <var>ID</var>}. (For details on how {@code content:} URIs |
| specify individual members of a group, see |
| <a href="{@docRoot}guide/topics/provider/content-providers.html">Content Providers</a>.) |
| |
| <dt>action: <code>android.intent.action.EDIT</code> |
| <br/>data: <code>content://com.google.provider.NotePad/notes/<var>ID</var></code></dt> |
| <dd>Asks the activity to display the content of the note identified |
| by {@code <var>ID</var>}, and to let the user edit it. If the user |
| saves the changes, the activity updates the data for the note in the |
| content provider.</dd> |
| |
| <dt>action: <code>android.intent.action.INSERT</code> |
| <br/>data: <code>content://com.google.provider.NotePad/notes</code></dt> |
| <dd>Asks the activity to create a new, empty note in the notes list at |
| <code>content://com.google.provider.NotePad/notes</code> |
| and allow the user to edit it. If the user saves the note, its URI |
| is returned to the caller. |
| </dd> |
| </dl> |
| |
| <p>The last activity, TitleEditor, |
| enables the user to edit the title of a note. This could be implemented |
| by directly invoking the activity (by explicitly setting its component |
| name in the Intent), without using an intent filter. But here we take |
| the opportunity to show how to publish alternative operations on existing |
| data: |
| </p> |
| |
| <pre><intent-filter android:label="@string/resolve_title"> |
| <action android:name="com.android.notepad.action.EDIT_TITLE" /> |
| <category android:name="android.intent.category.DEFAULT" /> |
| <category android:name="android.intent.category.ALTERNATIVE" /> |
| <category android:name="android.intent.category.SELECTED_ALTERNATIVE" /> |
| <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> |
| </intent-filter></pre> |
| |
| <p> |
| The single intent filter for this activity uses a custom action called |
| "<code>com.android.notepad.action.EDIT_TITLE</code>". It must be invoked on |
| a specific note (data type <code>vnd.android.cursor.item/vnd.google.note</code>), |
| like the previous {@code VIEW} and {@code EDIT} actions. However, here the |
| activity displays the title contained in the note data, not the content of |
| the note itself. |
| </p> |
| |
| <p> |
| In addition to supporting the usual {@code DEFAULT} category, the title |
| editor also supports two other standard categories: |
| <code>{@link android.content.Intent#CATEGORY_ALTERNATIVE ALTERNATIVE}</code> |
| and <code>{@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE |
| SELECTED_ALTERNATIVE}</code>. |
| These categories identify activities that can be presented to users in |
| a menu of options (much as the {@code LAUNCHER} category identifies |
| activities that should be presented to user in the application launcher). |
| Note that the filter also supplies an explicit label (via |
| <code>android:label="@string/resolve_title"</code>) to better control |
| what users see when presented with this activity as an alternative |
| action to the data they are currently viewing. (For more information |
| on these categories and building options menus, see the |
| <code>{@link android.content.pm.PackageManager#queryIntentActivityOptions |
| PackageManager.queryIntentActivityOptions()}</code> and |
| <code>{@link android.view.Menu#addIntentOptions Menu.addIntentOptions()}</code> |
| methods.) |
| </p> |
| |
| <p> |
| Given these capabilities, the following intent will resolve to the |
| TitleEditor activity: |
| </p> |
| |
| <dl style="margin-left: 2em"> |
| <dt>action: <code>com.android.notepad.action.EDIT_TITLE</code> |
| <br/>data: <code>content://com.google.provider.NotePad/notes/<var>ID</var></code></dt> |
| <dd>Asks the activity to display the title associated with note <var>ID</var>, and |
| allow the user to edit the title.</dd> |
| </dl> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |