| page.title=Intents and Intent Filters |
| @jd:body |
| |
| <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, 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: |
| |
| <ul> |
| |
| <p><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. |
| |
| <p><li>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 initiates the |
| service if it's not already running. |
| |
| <p><li>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. |
| |
| </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> |
| Intents can be divided into two groups: |
| |
| <ul> |
| |
| <p><li><i>Explicit intents</i> designate the target component by its class name. |
| They're typically used for application-internal messages — such as |
| an activity starting a subordinate service or launching a sister activity |
| — since component names would generally not be known to developers |
| of other applications. |
| |
| <p><li><i>Implicit intents</i> do not name the target. Instead, the |
| Android system determines the best component (or components) to respond |
| to the message. It compares the contents of the Intent object with |
| <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. |
| |
| |
| </ul> |
| |
| <p> |
| This document describes the rules Android uses to map intents to components — |
| how it determines which component should receive an intent message. |
| It begins with a description of Intent objects, and then describes intent filters |
| and how intents are tested against the filters. |
| |
| |
| <h2>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: |
| |
| <dl> |
| |
| <p><dt><b>Component class name</b></dt> |
| <dd>The fully qualified class name of the component that should handle the intent |
| — for example "{@code com.example.project.FreneticActivity}". |
| This field is optional (and it would not normally be set for broadcast intents, since |
| broadcasts are intended for more than a single receiver). However, if a class name |
| is specified, nothing else in the Intent |
| object matters for determining which component should get the intent; it will be |
| delivered to the named component. (Of course, the other contents of the intent will |
| matter to the component that receives it.) |
| |
| <p> |
| The component class 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><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. This is the only field |
| in the object that must be set. 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. |
| </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 full list of pre-defined action constants. |
| |
| <p> |
| You can define action strings of your own. Those you define should include the |
| application package as a prefix — for example: |
| "<code>com.example.project.DEBIT_ACCT</code>". 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><dt><b>Data</b></dt> |
| <dd>The data to be acted on. 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 a {@code mailto:} URI, the receiving activity would be called upon |
| to display a screen for composing an e-mail message, with the address filled in |
| from the URI. |
| |
| <p> |
| It's often important to know the type of data (its MIME type) in addition to its URI. |
| Typically, the type is inferred from the URI. But it can also be explicitly set. |
| 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 data and type are read by <code>{@link |
| android.content.Intent#getData getData()}</code> and <code>{@link |
| android.content.Intent#getType getType()}</code>. |
| |
| |
| <p><dt><b>Category</b></dt> |
| <dd>A string containing additional information about the kind of component |
| that should handle the intent. Categories generally apply only to activities. |
| |
| <p> |
| Any number of category descriptions can be placed in an Intent object. As it does for actions, the Intent class defines a number of category constants, including these: |
| |
| <p><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> |
| In addition to the role categories play in Intent objects, they have an |
| independent function in intent filters. As the examples above suggest, they |
| instruct the Android system how to treat the activity that owns the filter. For |
| example, {@code CATEGORY_HOME} defines the home activity. |
| |
| <p> |
| See the {@link android.content.Intent} class description for the full list of |
| categories. |
| |
| <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><dt><b>Extras</b></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. |
| |
| <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><dt><b>Launch instructions</b></dt> |
| <dd>Flags that 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. |
| |
| </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}../reference/available-intents.html">list of intents</a> |
| in the reference. |
| For example, the component that initiates phone calls can be activated by an |
| {@code ACTION_CALL} intent with a {@code tel:} URI specifying the phone number. |
| |
| |
| <h2>Intent Filters</h2> |
| |
| <p> |
| If an intent explicitly names a component class, Android delivers the intent to |
| an instance of that class, creating the instance if necessary. However, if the |
| intent does not designate a target by name, Android must find the appropriate |
| component to handle the request — 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 Intent object against |
| components' intent filters. |
| |
| <p> |
| To inform the system which 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 out unwanted |
| intents. An implicit intent (one that doesn't name a target class) is delivered |
| to a component only if it can pass through one of the component's filters. |
| If a component lacks any intent filters, it can be activated only by explicit |
| intents (those that specifically name its class). |
| |
| <p> |
| A component has separate filters for each job it can do, each face it can |
| present to the user. For example, if an activity can either display |
| a list of items that the user can select or display the full details of one of |
| the items, it would have a separate filter for each of these possibilities. |
| |
| <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 <intent-filter>} 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> |
| A filter has fields that parallel the action, data, and category fields of an |
| Intent object. A new 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 arriving intent that does not pass |
| through one of a component's filters might make it through on another. |
| |
| <p> |
| Each of the three tests is described in detail below: |
| |
| <dl> |
| |
| <p> |
| <dt><b>Action test</b></dt> |
| <dd>An {@code <intent-filter>} element in the manifest file lists actions |
| as {@code <action>} 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 — or it may not list any at all. |
| |
| <p> |
| To pass this test, the action specified in the {@link android.content.Intent} |
| object must match one of the actions listed in the filter. However, if the |
| filter doesn't list any actions, all actions are accepted, so all intents pass |
| the test. |
| |
| <p> |
| <dt><b>Category test</b></dt> |
| <dd>An {@code <intent-filter>} 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> |
| Many categories tell the Android system how to treat the component. For example, |
| "{@code android.intent.category.LAUNCHER}" (the {@code CATEGORY_LAUNCHER} constant |
| in code) instructs the system to include the activity in the screen showing |
| applications the user can launch. Some categories — like "{@code |
| android.intent.category.DEFAULT}" in the example above &mdash typically appear |
| only in filters, not in Intent objects. |
| |
| <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 in the intent. An intent with no |
| categories always passes this test, regardless of what's in the filter. |
| |
| <p> |
| <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:scheme="content" |
| android:host="com.example" |
| android:path="folder/*" . . . /> |
| <data android:scheme="content" |
| android:type="image/jpeg" . . . /> |
| . . . |
| </intent-filter></pre> |
| |
| <p> |
| Each {@code <data>} element can specify a URI and a data type (MIME type). |
| There are separate attributes — {@code scheme}, {@code host}, {@code port}, |
| and {@code path} — for each part of the URI: |
| |
| <dl><dd>{@code scheme://host:port/path}</dd></dl> |
| |
| <p> |
| For example, in the following URI, |
| |
| <dl><dd>{@code content://com.example.project:200/folder/subfolder/etc}</dd></dl> |
| |
| <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> |
| 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> |
| 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 specified 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> |
| A {@code <data>} element specifies a MIME type with the {@code type} attribute. |
| Both the Intent object and the filter can use the '*" wildcard for the subtype field |
| — for example, "{@code text/*}" or "{@code image/*}" — indicating any |
| subtype matches. |
| |
| <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: |
| |
| <ul> |
| |
| <p><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. |
| |
| <p><li>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>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>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 list only a data type. |
| |
| </ul> |
| |
| <p> |
| If an intent can pass through the filters of more than one component, the user |
| may be asked which component to activate. |
| |
| |
| |
| |
| |
| |
| |