intents-filters.jd revision df75bdcc5546112958a6a5834c1a7e060f88bc68
1page.title=Intents and Intent Filters 2page.tags="IntentFilter" 3@jd:body 4 5<div id="qv-wrapper"> 6<div id="qv"> 7 8<h2>In this document</h2> 9<ol> 10 <li><a href="#Types">Intent Types</a></li> 11 <li><a href="#Building">Building an Intent</a> 12 <ol> 13 <li><a href="#ExampleExplicit">Example explicit intent</a></li> 14 <li><a href="#ExampleSend">Example implicit intent</a></li> 15 <li><a href="#ForceChooser">Forcing an app chooser</a></li> 16 </ol> 17 </li> 18 <li><a href="#Receiving">Receiving an Implicit Intent</a> 19 <ol> 20 <li><a href="#ExampleFilters">Example filters</a></li> 21 </ol> 22 </li> 23 <li><a href="#PendingIntent">Using a Pending Intent</a></li> 24 <li><a href="#Resolution">Intent Resolution</a> 25 <ol> 26 <li><a href="#ActionTest">Action test</a></li> 27 <li><a href="#CategoryTest">Category test</a></li> 28 <li><a href="#DataTest">Data test</a></li> 29 <li><a href="#imatch">Intent matching</a></li> 30 </ol> 31 </li> 32</ol> 33 34<h2>See also</h2> 35<ol> 36<li><a href="{@docRoot}training/basics/intents/index.html">Interacting with Other Apps</a></li> 37<li><a href="{@docRoot}training/sharing/index.html">Sharing Content</a></li> 38</ol> 39 40</div> 41</div> 42 43 44 45 46<p>An {@link android.content.Intent} is a messaging object you can use to request an action 47from another <a href="{@docRoot}guide/components/fundamentals.html#Components">app component</a>. 48Although intents facilitate communication between components in several ways, there are three 49fundamental use-cases:</p> 50 51<ul> 52<li><b>To start an activity:</b> 53<p>An {@link android.app.Activity} represents a single screen in an app. You can start a new 54instance of an {@link android.app.Activity} by passing an {@link android.content.Intent} 55to {@link android.content.Context#startActivity startActivity()}. The {@link android.content.Intent} 56describes the activity to start and carries any necessary data.</p> 57 58<p>If you want to receive a result from the activity when it finishes, 59call {@link android.app.Activity#startActivityForResult 60startActivityForResult()}. Your activity receives the result 61as a separate {@link android.content.Intent} object in your activity's {@link 62android.app.Activity#onActivityResult onActivityResult()} callback. 63For more information, see the <a 64href="{@docRoot}guide/components/activities.html">Activities</a> guide.</p></li> 65 66<li><b>To start a service:</b> 67<p>A {@link android.app.Service} is a component that performs operations in the background 68without a user interface. You can start a service to perform a one-time operation 69(such as download a file) by passing an {@link android.content.Intent} 70to {@link android.content.Context#startService startService()}. The {@link android.content.Intent} 71describes the service to start and carries any necessary data.</p> 72 73<p>If the service is designed with a client-server interface, you can bind to the service 74from another component by passing an {@link android.content.Intent} to {@link 75android.content.Context#bindService bindService()}</code>. For more information, see the <a 76href="{@docRoot}guide/components/services.html">Services</a> guide.</p></li> 77 78<li><b>To deliver a broadcast:</b> 79<p>A broadcast is a message that any app can receive. The system delivers various 80broadcasts for system events, such as when the system boots up or the device starts charging. 81You can deliver a broadcast to other apps by passing an {@link android.content.Intent} 82to {@link android.content.Context#sendBroadcast(Intent) sendBroadcast()}, 83{@link android.content.Context#sendOrderedBroadcast(Intent, String) 84sendOrderedBroadcast()}, or {@link 85android.content.Context#sendStickyBroadcast sendStickyBroadcast()}.</p> 86</li> 87</ul> 88 89 90 91 92<h2 id="Types">Intent Types</h2> 93 94<p>There are two types of intents:</p> 95 96<ul> 97<li><b>Explicit intents</b> specify the component to start by name (the 98fully-qualified class name). You'll typically use an explicit intent to start a component in 99your own app, because you know the class name of the activity or service you want to start. For 100example, start a new activity in response to a user action or start a service to download 101a file in the background.</li> 102 103<li><b>Implicit intents</b> do not name a specific component, but instead declare a general action 104to perform, which allows a component from another app to handle it. For example, if you want to 105show the user a location on a map, you can use an implicit intent to request that another capable 106app show a specified location on a map.</li> 107</ul> 108 109<p>When you create an explicit intent to start an activity or service, the system immediately 110starts the app component specified in the {@link android.content.Intent} object.</p> 111 112<div class="figure" style="width:446px"> 113<img src="{@docRoot}images/components/intent-filters@2x.png" width="446" alt=""/> 114<p class="img-caption"><strong>Figure 1.</strong> Illustration of how an implicit intent is 115delivered through the system to start another activity: <b>[1]</b> <em>Activity A</em> creates an 116{@link android.content.Intent} with an action description and passes it to {@link 117android.content.Context#startActivity startActivity()}. <b>[2]</b> The Android System searches all 118apps for an intent filter that matches the intent. When a match is found, <b>[3]</b> the system 119starts the matching activity (<em>Activity B</em>) by invoking its {@link 120android.app.Activity#onCreate onCreate()} method and passing it the {@link android.content.Intent}. 121</p> 122</div> 123 124<p>When you create an implicit intent, the Android system finds the appropriate component to start 125by comparing the contents of the intent to the <em>intent filters</em> declared in the <a href= 126"{@docRoot}guide/topics/manifest/manifest-intro.html">manifest file</a> of other apps on the 127device. If the intent matches an intent filter, the system starts that component and delivers it 128the {@link android.content.Intent} object. If multiple intent filters are compatible, the system 129displays a dialog so the user can pick which app to use.</p> 130 131<p>An intent filter is an expression in an app's manifest file that 132specifies the type of intents that the component 133would like to receive. For instance, by declaring an intent filter for an activity, 134you make it possible for other apps to directly start your activity with a certain kind of intent. 135Likewise, if you do <em>not</em> declare any intent filters for an activity, then it can be started 136only with an explicit intent.</p> 137 138<p class="caution"><strong>Caution:</strong> To ensure your app is secure, always use an explicit 139intent when starting a {@link android.app.Service} and do not 140declare intent filters for your services. Using an implicit intent to start a service is a 141security hazard because you cannot be certain what service will respond to the intent, 142and the user cannot see which service starts.</p> 143 144 145 146 147 148<h2 id="Building">Building an Intent</h2> 149 150<p>An {@link android.content.Intent} object carries information that the Android system uses 151to determine which component to start (such as the exact component name or component 152category that should receive the intent), plus information that the recipient component uses in 153order to properly perform the action (such as the action to take and the data to act upon).</p> 154 155 156<p>The primary information contained in an {@link android.content.Intent} is the following:</p> 157 158<dl> 159 160<dt><b>Component name</b></dt> 161<dd>The name of the component to start. 162 163<p>This is optional, but it's the critical piece of information that makes an intent 164<b>explicit</b>, meaning that the intent should be delivered only to the app component 165defined by the component name. Without a component name, the intent is <b>implicit</b> and the 166system decides which component should receive the intent based on the other intent information 167(such as the action, data, and category—described below). So if you need to start a specific 168component in your app, you should specify the component name.</p> 169 170<p class="note"><strong>Note:</strong> When starting a {@link android.app.Service}, you should 171<strong>always specify the component name</strong>. Otherwise, you cannot be certain what service 172will respond to the intent, and the user cannot see which service starts.</p> 173 174<p>This field of the {@link android.content.Intent} is a 175{@link android.content.ComponentName} object, which you can specify using a fully 176qualified class name of the target component, including the package name of the app. For example, 177{@code com.example.ExampleActivity}. You can set the component name with {@link 178android.content.Intent#setComponent setComponent()}, {@link android.content.Intent#setClass 179setClass()}, {@link android.content.Intent#setClassName(String, String) setClassName()}, or with the 180{@link android.content.Intent} constructor.</p> 181 182</dd> 183 184<p><dt><b>Action</b></dt> 185<dd>A string that specifies the generic action to perform (such as <em>view</em> or <em>pick</em>). 186 187<p>In the case of a broadcast intent, this is the action that took place and is being reported. 188The action largely determines how the rest of the intent is structured—particularly 189what is contained in the data and extras. 190 191<p>You can specify your own actions for use by intents within your app (or for use by other 192apps to invoke components in your app), but you should usually use action constants 193defined by the {@link android.content.Intent} class or other framework classes. Here are some 194common actions for starting an activity:</p> 195 196<dl> 197<dt>{@link android.content.Intent#ACTION_VIEW}</dt> 198 <dd>Use this action in an intent with {@link 199 android.content.Context#startActivity startActivity()} when you have some information that 200 an activity can show to the user, such as a photo to view in a gallery app, or an address to 201 view in a map app.</dd> 202 203<dt>{@link android.content.Intent#ACTION_SEND}</dt> 204 <dd>Also known as the "share" intent, you should use this in an intent with {@link 205 android.content.Context#startActivity startActivity()} when you have some data that the user can 206 share through another app, such as an email app or social sharing app.</dd> 207</dl> 208 209<p>See the {@link android.content.Intent} class reference for more 210constants that define generic actions. Other actions are defined 211elsewhere in the Android framework, such as in {@link android.provider.Settings} for actions 212that open specific screens in the system's Settings app.</p> 213 214<p>You can specify the action for an intent with {@link android.content.Intent#setAction 215setAction()} or with an {@link android.content.Intent} constructor.</p> 216 217<p>If you define your own actions, be sure to include your app's package name 218as a prefix. For example:</p> 219<pre>static final String ACTION_TIMETRAVEL = "com.example.action.TIMETRAVEL";</pre> 220</dd> 221 222<dt><b>Data</b></dt> 223<dd>The URI (a {@link android.net.Uri} object) that references the data to be acted on and/or the 224MIME type of that data. The type of data supplied is generally dictated by the intent's action. For 225example, if the action is {@link android.content.Intent#ACTION_EDIT}, the data should contain the 226URI of the document to edit. 227 228<p>When creating an intent, 229it's often important to specify the type of data (its MIME type) in addition to its URI. 230For example, an activity that's able to display images probably won't be able 231to play an audio file, even though the URI formats could be similar. 232So specifying the MIME type of your data helps the Android 233system find the best component to receive your intent. 234However, the MIME type can sometimes be inferred from the URI—particularly when the data is a 235{@code content:} URI, which indicates the data is located on the device and controlled by a 236{@link android.content.ContentProvider}, which makes the data MIME type visible to the system.</p> 237 238<p>To set only the data URI, call {@link android.content.Intent#setData setData()}. 239To set only the MIME type, call {@link android.content.Intent#setType setType()}. If necessary, you 240can set both explicitly with {@link 241android.content.Intent#setDataAndType setDataAndType()}.</p> 242 243<p class="caution"><strong>Caution:</strong> If you want to set both the URI and MIME type, 244<strong>do not</strong> call {@link android.content.Intent#setData setData()} and 245{@link android.content.Intent#setType setType()} because they each nullify the value of the other. 246Always use {@link android.content.Intent#setDataAndType setDataAndType()} to set both 247URI and MIME type.</p> 248</dd> 249 250<p><dt><b>Category</b></dt> 251<dd>A string containing additional information about the kind of component 252that should handle the intent. Any number of category descriptions can be 253placed in an intent, but most intents do not require a category. 254Here are some common categories: 255 256<dl> 257<dt>{@link android.content.Intent#CATEGORY_BROWSABLE}</dt> 258 <dd>The target activity allows itself to be started by a web browser to display data 259 referenced by a link—such as an image or an e-mail message. 260 </dd> 261<dt>{@link android.content.Intent#CATEGORY_LAUNCHER}</dt> 262 <dd>The activity is the initial activity of a task and is listed in 263 the system's application launcher. 264 </dd> 265</dl> 266 267<p>See the {@link android.content.Intent} class description for the full list of 268categories.</p> 269 270<p>You can specify a category with {@link android.content.Intent#addCategory addCategory()}.</p> 271</dd> 272</dl> 273 274 275<p>These properties listed above (component name, action, data, and category) represent the 276defining characteristics of an intent. By reading these properties, the Android system 277is able to resolve which app component it should start.</p> 278 279<p>However, an intent can carry additional information that does not affect 280how it is resolved to an app component. An intent can also supply:</p> 281 282<dl> 283<dt><b>Extras</b></dt> 284<dd>Key-value pairs that carry additional information required to accomplish the requested action. 285Just as some actions use particular kinds of data URIs, some actions also use particular extras. 286 287<p>You can add extra data with various {@link android.content.Intent#putExtra putExtra()} methods, 288each accepting two parameters: the key name and the value. 289You can also create a {@link android.os.Bundle} object with all the extra data, then insert 290the {@link android.os.Bundle} in the {@link android.content.Intent} with {@link 291android.content.Intent#putExtras putExtras()}.</p> 292 293<p>For example, when creating an intent to send an email with 294{@link android.content.Intent#ACTION_SEND}, you can specify the "to" recipient with the 295{@link android.content.Intent#EXTRA_EMAIL} key, and specify the "subject" with the 296{@link android.content.Intent#EXTRA_SUBJECT} key.</p> 297 298<p>The {@link android.content.Intent} class specifies many {@code EXTRA_*} constants 299for standardized data types. If you need to declare your own extra keys (for intents that 300your app receives), be sure to include your app's package name 301as a prefix. For example:</p> 302<pre>static final String EXTRA_GIGAWATTS = "com.example.EXTRA_GIGAWATTS";</pre> 303</dd> 304 305<dt><b>Flags</b></dt> 306<dd>Flags defined in the {@link android.content.Intent} class that function as metadata for the 307intent. The flags may instruct the Android system how to launch an activity (for example, which 308<a href="{@docRoot}guide/components/tasks-and-back-stack.html">task</a> the activity should belong 309to) and how to treat it after it's launched (for example, whether it belongs in the list of recent 310activities). 311 312<p>For more information, see the {@link android.content.Intent#setFlags setFlags()} method.</p> 313</dd> 314 315</dl> 316 317 318 319 320<h3 id="ExampleExplicit">Example explicit intent</h3> 321 322<p>An explicit intent is one that you use to launch a specific app component, such as 323a particular activity or service in your app. To create an explicit intent, define 324the component name for the {@link android.content.Intent} object—all 325other intent properties are optional.</p> 326 327<p>For example, if you built a service in your app, named {@code DownloadService}, 328designed to download a file from the web, you can start it with the following code:</p> 329 330<pre> 331// Executed in an Activity, so 'this' is the {@link android.content.Context} 332// The fileUrl is a string URL, such as "http://www.example.com/image.png" 333Intent downloadIntent = new Intent(this, DownloadService.class); 334downloadIntent.setData({@link android.net.Uri#parse Uri.parse}(fileUrl)); 335startService(downloadIntent); 336</pre> 337 338<p>The {@link android.content.Intent#Intent(Context,Class)} 339constructor supplies the app {@link android.content.Context} and the 340component a {@link java.lang.Class} object. As such, 341this intent explicitly starts the {@code DownloadService} class in the app.</p> 342 343<p>For more information about building and starting a service, see the 344<a href="{@docRoot}guide/components/services.html">Services</a> guide.</p> 345 346 347 348 349<h3 id="ExampleSend">Example implicit intent</h3> 350 351<p>An implicit intent specifies an action that can invoke any app on the device able 352to perform the action. Using an implicit intent is useful when your app cannot perform the 353action, but other apps probably can and you'd like the user to pick which app to use.</p> 354 355<p>For example, if you have content you want the user to share with other people, create an intent 356with the {@link android.content.Intent#ACTION_SEND} action 357and add extras that specify the content to share. When you call 358{@link android.content.Context#startActivity startActivity()} with that intent, the user can 359pick an app through which to share the content.</p> 360 361<p class="caution"><strong>Caution:</strong> It's possible that a user won't have <em>any</em> 362apps that handle the implicit intent you send to {@link android.content.Context#startActivity 363startActivity()}. If that happens, the call will fail and your app will crash. To verify 364that an activity will receive the intent, call {@link android.content.Intent#resolveActivity 365resolveActivity()} on your {@link android.content.Intent} object. If the result is non-null, 366then there is at least one app that can handle the intent and it's safe to call 367{@link android.content.Context#startActivity startActivity()}. If the result is null, 368you should not use the intent and, if possible, you should disable the feature that issues 369the intent.</p> 370 371 372<pre> 373// Create the text message with a string 374Intent sendIntent = new Intent(); 375sendIntent.setAction(Intent.ACTION_SEND); 376sendIntent.putExtra(Intent.EXTRA_TEXT, textMessage); 377sendIntent.setType({@link 378 org.apache.http.protocol.HTTP#PLAIN_TEXT_TYPE 379 HTTP.PLAIN_TEXT_TYPE}); // "text/plain" MIME type 380 381// Verify that the intent will resolve to an activity 382if (sendIntent.resolveActivity(getPackageManager()) != null) { 383 startActivity(sendIntent); 384} 385</pre> 386 387<p class="note"><strong>Note:</strong> In this case, a URI is not used, but the intent's data type 388is declared to specify the content carried by the extras.</p> 389 390 391<p>When {@link android.content.Context#startActivity startActivity()} is called, the system 392examines all of the installed apps to determine which ones can handle this kind of intent (an 393intent with the {@link android.content.Intent#ACTION_SEND} action and that carries "text/plain" 394data). If there's only one app that can handle it, that app opens immediately and is given the 395intent. If multiple activities accept the intent, the system 396displays a dialog so the user can pick which app to use..</p> 397 398 399<div class="figure" style="width:200px"> 400 <img src="{@docRoot}images/training/basics/intent-chooser.png" alt=""> 401 <p class="img-caption"><strong>Figure 2.</strong> A chooser dialog.</p> 402</div> 403 404<h3 id="ForceChooser">Forcing an app chooser</h3> 405 406<p>When there is more than one app that responds to your implicit intent, 407the user can select which app to use and make that app the default choice for the 408action. This is nice when performing an action for which the user 409probably wants to use the same app from now on, such as when opening a web page (users 410often prefer just one web browser) .</p> 411 412<p>However, if multiple apps can respond to the intent and the user might want to use a different 413app each time, you should explicitly show a chooser dialog. The chooser dialog asks the 414user to select which app to use for the action every time (the user cannot select a default app for 415the action). For example, when your app performs "share" with the {@link 416android.content.Intent#ACTION_SEND} action, users may want to share using a different app depending 417on their current situation, so you should always use the chooser dialog, as shown in figure 2.</p> 418 419 420 421 422<p>To show the chooser, create an {@link android.content.Intent} using {@link 423android.content.Intent#createChooser createChooser()} and pass it to {@link 424android.app.Activity#startActivity startActivity()}. For example:</p> 425 426<pre> 427Intent intent = new Intent(Intent.ACTION_SEND); 428... 429 430// Always use string resources for UI text. 431// This says something like "Share this photo with" 432String title = getResources().getString(R.string.chooser_title); 433// Create intent to show chooser 434Intent chooser = Intent.createChooser(intent, title); 435 436// Verify the intent will resolve to at least one activity 437if (sendIntent.resolveActivity(getPackageManager()) != null) { 438 startActivity(sendIntent); 439} 440</pre> 441 442<p>This displays a dialog with a list of apps that respond to the intent passed to the {@link 443android.content.Intent#createChooser createChooser()} method and uses the supplied text as the 444dialog title.</p> 445 446 447 448 449 450 451 452 453 454<h2 id="Receiving">Receiving an Implicit Intent</h2> 455 456<p>To advertise which implicit intents your app can receive, declare one or more intent filters for 457each of your app components with an <a href= 458"{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code <intent-filter>}</a> 459element in your <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">manifest file</a>. 460Each intent filter specifies the type of intents it accepts based on the intent's action, 461data, and category. The system will deliver an implicit intent to your app component only if the 462intent can pass through one of your intent filters.</p> 463 464<p class="note"><strong>Note:</strong> An explicit intent is always delivered to its target, 465regardless of any intent filters the component declares.</p> 466 467<p>An app component should declare separate filters for each unique job it can do. 468For example, one activity in an image gallery app may have two filters: one filter 469to view an image, and another filter to edit an image. When the activity starts, 470it inspects the {@link android.content.Intent} and decides how to behave based on the information 471in the {@link android.content.Intent} (such as to show the editor controls or not).</p> 472 473<p>Each intent filter is defined by an <a 474href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code <intent-filter>}</a> 475element in the app's manifest file, nested in the corresponding app component (such 476as an <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> 477element). Inside the <a 478href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code <intent-filter>}</a>, 479you can specify the type of intents to accept using one or more 480of these three elements:</p> 481 482<dl> 483<dt><a href="{@docRoot}guide/topics/manifest/action-element.html">{@code <action>}</a></dt> 484 <dd>Declares the intent action accepted, in the {@code name} attribute. The value 485 must be the literal string value of an action, not the class constant.</dd> 486<dt><a href="{@docRoot}guide/topics/manifest/data-element.html">{@code <data>}</a></dt> 487 <dd>Declares the type of data accepted, using one or more attributes that specify various 488 aspects of the data URI (<code>scheme</code>, <code>host</code>, <code>port</code>, 489 <code>path</code>, etc.) and MIME type.</dd> 490<dt><a href="{@docRoot}guide/topics/manifest/category-element.html">{@code <category>}</a></dt> 491 <dd>Declares the intent category accepted, in the {@code name} attribute. The value 492 must be the literal string value of an action, not the class constant. 493 494 <p class="note"><strong>Note:</strong> In order to receive implicit intents, you 495 <strong>must include</strong> the 496 {@link android.content.Intent#CATEGORY_DEFAULT} category in the intent filter. The methods 497 {@link android.app.Activity#startActivity startActivity()} and 498 {@link android.app.Activity#startActivityForResult startActivityForResult()} treat all intents 499 as if they declared the {@link android.content.Intent#CATEGORY_DEFAULT} category. 500 If you do not declare this category in your intent filter, no implicit intents will resolve to 501 your activity.</p> 502 </dd> 503</dl> 504 505<p>For example, here's an activity declaration with an intent filter to receive an 506{@link android.content.Intent#ACTION_SEND} intent when the data type is text:</p> 507 508<pre> 509<activity android:name="ShareActivity"> 510 <intent-filter> 511 <action android:name="android.intent.action.SEND"/> 512 <category android:name="android.intent.category.DEFAULT"/> 513 <data android:mimeType="text/plain"/> 514 </intent-filter> 515</activity> 516</pre> 517 518<p>It's okay to create a filter that includes more than one instance of 519<a href="{@docRoot}guide/topics/manifest/action-element.html">{@code <action>}</a>, 520<a href="{@docRoot}guide/topics/manifest/data-element.html">{@code <data>}</a>, or 521<a href="{@docRoot}guide/topics/manifest/category-element.html">{@code <category>}</a>. 522If you do, you simply need to be certain that the component can handle any and all combinations 523of those filter elements.</p> 524 525<p>When you want to handle multiple kinds of intents, but only in specific combinations of 526action, data, and category type, then you need to create multiple intent filters.</p> 527 528 529<div class="sidebox-wrapper"> 530<div class="sidebox"> 531<h2>Restricting access to components</h2> 532<p>Using an intent filter is not a secure way to prevent other apps from starting 533your components. Although intent filters restrict a component to respond to only 534certain kinds of implicit intents, another app can potentially start your app component 535by using an explicit intent if the developer determines your component names. 536If it's important that <em>only your own app</em> is able to start one of your components, 537set the <a href="{@docRoot}guide/topics/manifest/activity-element.html#exported">{@code 538exported}</a> attribute to {@code "false"} for that component. 539</p> 540</div> 541</div> 542 543<p>An implicit intent is tested against a filter by comparing the intent to each of the 544three elements. To be delivered to the component, the intent must pass all three tests. 545If it fails to match even one of them, the Android system won't deliver the intent to the 546component. However, because a component may have multiple intent filters, an intent that does 547not pass through one of a component's filters might make it through on another filter. 548More information about how the system resolves intents is provided in the section below 549about <a href="#Resolution">Intent Resolution</a>.</p> 550 551<p class="caution"><strong>Caution:</strong> To avoid inadvertently running a different app's 552{@link android.app.Service}, always use an explicit intent to start your own service and do not 553declare intent filters for your service.</p> 554 555<p class="note"><strong>Note:</strong> 556For all activities, you must declare your intent filters in the manifest file. 557However, filters for broadcast receivers can be registered dynamically by calling 558{@link android.content.Context#registerReceiver(BroadcastReceiver, IntentFilter, String, 559Handler) registerReceiver()}. You can then unregister the receiver with {@link 560android.content.Context#unregisterReceiver unregisterReceiver()}. Doing so allows your app 561to listen for specific broadcasts during only a specified period of time while your app 562is running.</p> 563 564 565 566 567 568 569 570<h3 id="ExampleFilters">Example filters</h3> 571 572<p>To better understand some of the intent filter behaviors, look at the following snippet 573from the manifest file of a social-sharing app.</p> 574 575<pre> 576<activity android:name="MainActivity"> 577 <!-- This activity is the main entry, should appear in app launcher --> 578 <intent-filter> 579 <action android:name="android.intent.action.MAIN" /> 580 <category android:name="android.intent.category.LAUNCHER" /> 581 </intent-filter> 582</activity> 583 584<activity android:name="ShareActivity"> 585 <!-- This activity handles "SEND" actions with text data --> 586 <intent-filter> 587 <action android:name="android.intent.action.SEND"/> 588 <category android:name="android.intent.category.DEFAULT"/> 589 <data android:mimeType="text/plain"/> 590 </intent-filter> 591 <!-- This activity also handles "SEND" and "SEND_MULTIPLE" with media data --> 592 <intent-filter> 593 <action android:name="android.intent.action.SEND"/> 594 <action android:name="android.intent.action.SEND_MULTIPLE"/> 595 <category android:name="android.intent.category.DEFAULT"/> 596 <data android:mimeType="application/vnd.google.panorama360+jpg"/> 597 <data android:mimeType="image/*"/> 598 <data android:mimeType="video/*"/> 599 </intent-filter> 600</activity> 601</pre> 602 603<p>The first activity, {@code MainActivity}, is the app's main entry point—the activity that 604opens when the user initially launches the app with the launcher icon:</p> 605<ul> 606 <li>The {@link android.content.Intent#ACTION_MAIN} action 607 indicates this is the main entry point and does not expect any intent data.</li> 608 <li>The {@link android.content.Intent#CATEGORY_LAUNCHER} category indicates that this activity's 609 icon should be placed in the system's app launcher. If the <a 610 href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element 611 does not specify an icon with {@code icon}, then the system uses the icon from the <a 612 href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> 613 element.</li> 614</ul> 615<p>These two must be paired together in order for the activity to appear in the app launcher.</p> 616 617<p>The second activity, {@code ShareActivity}, is intended to facilitate sharing text and media 618content. Although users might enter this activity by navigating to it from {@code MainActivity}, 619they can also enter {@code ShareActivity} directly from another app that issues an implicit 620intent matching one of the two intent filters.</p> 621 622<p class="note"><strong>Note:</strong> The MIME type, 623<a href="https://developers.google.com/panorama/android/">{@code 624application/vnd.google.panorama360+jpg}</a>, is a special data type that specifies 625panoramic photos, which you can handle with the <a 626href="{@docRoot}reference/com/google/android/gms/panorama/package-summary.html">Google 627panorama</a> APIs.</p> 628 629 630 631 632 633 634 635 636 637 638 639 640 641<h2 id="PendingIntent">Using a Pending Intent</h2> 642 643<p>A {@link android.app.PendingIntent} object is a wrapper around an {@link 644android.content.Intent} object. The primary purpose of a {@link android.app.PendingIntent} 645is to grant permission to a foreign application 646to use the contained {@link android.content.Intent} as if it were executed from your 647app's own process.</p> 648 649<p>Major use cases for a pending intent include:</p> 650<ul> 651 <li>Declare an intent to be executed when the user performs an action with your <a 652 href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notification</a> 653 (the Android system's {@link android.app.NotificationManager} 654 executes the {@link android.content.Intent}). 655 <li>Declare an intent to be executed when the user performs an action with your 656 <a href="{@docRoot}guide/topics/appwidgets/index.html">App Widget</a> 657 (the Home screen app executes the {@link android.content.Intent}). 658 <li>Declare an intent to be executed at a specified time in the future (the Android 659 system's {@link android.app.AlarmManager} executes the {@link android.content.Intent}). 660</ul> 661 662<p>Because each {@link android.content.Intent} object is designed to be handled by a specific 663type of app component (either an {@link android.app.Activity}, a {@link android.app.Service}, or 664a {@link android.content.BroadcastReceiver}), so too must a {@link android.app.PendingIntent} be 665created with the same consideration. When using a pending intent, your app will not 666execute the intent with a call such as {@link android.content.Context#startActivity 667startActivity()}. You must instead declare the intended component type when you create the 668{@link android.app.PendingIntent} by calling the respective creator method:</p> 669 670<ul> 671 <li>{@link android.app.PendingIntent#getActivity PendingIntent.getActivity()} for an 672 {@link android.content.Intent} that starts an {@link android.app.Activity}.</li> 673 <li>{@link android.app.PendingIntent#getService PendingIntent.getService()} for an 674 {@link android.content.Intent} that starts a {@link android.app.Service}.</li> 675 <li>{@link android.app.PendingIntent#getBroadcast PendingIntent.getBroadcast()} for a 676 {@link android.content.Intent} that starts an {@link android.content.BroadcastReceiver}.</li> 677</ul> 678 679<p>Unless your app is <em>receiving</em> pending intents from other apps, 680the above methods to create a {@link android.app.PendingIntent} are the only 681{@link android.app.PendingIntent} methods you'll probably ever need.</p> 682 683<p>Each method takes the current app {@link android.content.Context}, the 684{@link android.content.Intent} you want to wrap, and one or more flags that specify 685how the intent should be used (such as whether the intent can be used more than once).</p> 686 687<p>More information about using pending intents is provided with the documentation for each 688of the respective use cases, such as in the <a 689href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notifications</a> 690and <a href="{@docRoot}guide/topics/appwidgets/index.html">App Widgets</a> API guides.</p> 691 692 693 694 695 696 697 698<h2 id="Resolution">Intent Resolution</h2> 699 700 701<p>When the system receives an implicit intent to start an activity, it searches for the 702best activity for the intent by comparing the intent to intent filters based on three aspects:</p> 703 704<ul> 705 <li>The intent action 706 <li>The intent data (both URI and data type) 707 <li>The intent category 708</ul> 709 710<p>The following sections describe how an intents are matched to the appropriate component(s) 711in terms of how the intent filter is declared in an app's manifest file.</p> 712 713 714<h3 id="ActionTest">Action test</h3> 715 716<p>To specify accepted intent actions, an intent filter can declare zero or more 717<a href="{@docRoot}guide/topics/manifest/action-element.html">{@code 718<action>}</a> elements. For example:</p> 719 720<pre> 721<intent-filter> 722 <action android:name="android.intent.action.EDIT" /> 723 <action android:name="android.intent.action.VIEW" /> 724 ... 725</intent-filter> 726</pre> 727 728<p>To get through this filter, the action specified in the {@link android.content.Intent} 729 must match one of the actions listed in the filter.</p> 730 731<p>If the filter does not list any actions, there is nothing for an 732intent to match, so all intents fail the test. However, if an {@link android.content.Intent} 733does not specify an action, it will pass the test (as long as the filter 734contains at least one action).</p> 735 736 737 738<h3 id="CategoryTest">Category test</h3> 739 740<p>To specify accepted intent categories, an intent filter can declare zero or more 741<a href="{@docRoot}guide/topics/manifest/category-element.html">{@code 742<category>}</a> elements. For example:</p> 743 744<pre> 745<intent-filter> 746 <category android:name="android.intent.category.DEFAULT" /> 747 <category android:name="android.intent.category.BROWSABLE" /> 748 ... 749</intent-filter> 750</pre> 751 752<p>For an intent to pass the category test, every category in the {@link android.content.Intent} 753must match a category in the filter. The reverse is not necessary—the intent filter may 754declare more categories than are specified in the {@link android.content.Intent} and the 755{@link android.content.Intent} will still pass. Therefore, an intent with no categories should 756always pass this test, regardless of what categories are declared in the filter.</p> 757 758<p class="note"><strong>Note:</strong> 759Android automatically applies the the {@link android.content.Intent#CATEGORY_DEFAULT} category 760to all implicit intents passed to {@link 761android.content.Context#startActivity startActivity()} and {@link 762android.app.Activity#startActivityForResult startActivityForResult()}. 763So if you want your activity to receive implicit intents, it must 764include a category for {@code "android.intent.category.DEFAULT"} in its intent filters (as 765shown in the previous {@code <intent-filter>} example.</p> 766 767 768 769<h3 id="DataTest">Data test</h3> 770 771<p>To specify accepted intent data, an intent filter can declare zero or more 772<a href="{@docRoot}guide/topics/manifest/data-element.html">{@code 773<data>}</a> elements. For example:</p> 774 775<pre> 776<intent-filter> 777 <data android:mimeType="video/mpeg" android:scheme="http" ... /> 778 <data android:mimeType="audio/mpeg" android:scheme="http" ... /> 779 ... 780</intent-filter> 781</pre> 782 783<p>Each <code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> 784element can specify a URI structure and a data type (MIME media type). There are separate 785attributes — {@code scheme}, {@code host}, {@code port}, 786and {@code path} — for each part of the URI: 787</p> 788 789<p style="margin-left: 2em">{@code <scheme>://<host>:<port>/<path>}</p> 790 791<p> 792For example: 793</p> 794 795<p style="margin-left: 2em">{@code content://com.example.project:200/folder/subfolder/etc}</p> 796 797<p>In this URI, the scheme is {@code content}, the host is {@code com.example.project}, 798the port is {@code 200}, and the path is {@code folder/subfolder/etc}. 799</p> 800 801<p>Each of these attributes is optional in a <a 802href="{@docRoot}guide/topics/manifest/data-element.html">{@code <data>}</a> element, 803but there are linear dependencies:</p> 804<ul> 805 <li>If a scheme is not specified, the host is ignored.</li> 806 <li>If a host is not specified, the port is ignored.</li> 807 <li>If both the scheme and host are not specified, the path is ignored.</li> 808</ul> 809 810<p>When the URI in an intent is compared to a URI specification in a filter, 811it's compared only to the parts of the URI included in the filter. For example:</p> 812<ul> 813 <li>If a filter specifies only a scheme, all URIs with that scheme match 814the filter.</li> 815 <li>If a filter specifies a scheme and an authority but no path, all URIs 816with the same scheme and authority pass the filter, regardless of their paths.</li> 817 <li>If a filter specifies a scheme, an authority, and a path, only URIs with the same scheme, 818authority, and path pass the filter.</li> 819</ul> 820 821<p class="note"><strong>Note:</strong> A path specification can 822contain a wildcard asterisk (*) to require only a partial match of the path name.</p> 823 824<p>The data test compares both the URI and the MIME type in the intent to a URI 825and MIME type specified in the filter. The rules are as follows: 826</p> 827 828<ol type="a"> 829<li>An intent that contains neither a URI nor a MIME type passes the 830test only if the filter does not specify any URIs or MIME types.</li> 831 832<li>An intent that contains a URI but no MIME type (neither explicit nor inferable from the 833URI) passes the test only if its URI matches the filter's URI format 834and the filter likewise does not specify a MIME type.</li> 835 836<li>An intent that contains a MIME type but not a URI passes the test 837only if the filter lists the same MIME type and does not specify a URI format.</li> 838 839<li>An intent that contains both a URI and a MIME type (either explicit or inferable from the 840URI) passes the MIME type part of the test only if that 841type matches a type listed in the filter. It passes the URI part of the test 842either if its URI matches a URI in the filter or if it has a {@code content:} 843or {@code file:} URI and the filter does not specify a URI. In other words, 844a component is presumed to support {@code content:} and {@code file:} data if 845its filter lists <em>only</em> a MIME type.</p></li> 846</ol> 847 848<p> 849This last rule, rule (d), reflects the expectation 850that components are able to get local data from a file or content provider. 851Therefore, their filters can list just a data type and do not need to explicitly 852name the {@code content:} and {@code file:} schemes. 853This is a typical case. A <a 854href="{@docRoot}guide/topics/manifest/data-element.html">{@code <data>}</a> element 855like the following, for example, tells Android that the component can get image data from a content 856provider and display it: 857</p> 858 859<pre> 860<intent-filter> 861 <data android:mimeType="image/*" /> 862 ... 863</intent-filter></pre> 864 865<p> 866Because most available data is dispensed by content providers, filters that 867specify a data type but not a URI are perhaps the most common. 868</p> 869 870<p> 871Another common configuration is filters with a scheme and a data type. For 872example, a <a 873href="{@docRoot}guide/topics/manifest/data-element.html">{@code <data>}</a> 874element like the following tells Android that 875the component can retrieve video data from the network in order to perform the action: 876</p> 877 878<pre> 879<intent-filter> 880 <data android:scheme="http" android:type="video/*" /> 881 ... 882</intent-filter></pre> 883 884 885 886<h3 id="imatch">Intent matching</h3> 887 888<p>Intents are matched against intent filters not only to discover a target 889component to activate, but also to discover something about the set of 890components on the device. For example, the Home app populates the app launcher 891by finding all the activities with intent filters that specify the 892{@link android.content.Intent#ACTION_MAIN} action and 893{@link android.content.Intent#CATEGORY_LAUNCHER} category.</p> 894 895<p>Your application can use intent matching in a similar way. 896The {@link android.content.pm.PackageManager} has a set of {@code query...()} 897methods that return all components that can accept a particular intent, and 898a similar series of {@code resolve...()} methods that determine the best 899component to respond to an intent. For example, 900{@link android.content.pm.PackageManager#queryIntentActivities 901queryIntentActivities()} returns a list of all activities that can perform 902the intent passed as an argument, and {@link 903android.content.pm.PackageManager#queryIntentServices 904queryIntentServices()} returns a similar list of services. 905Neither method activates the components; they just list the ones that 906can respond. There's a similar method, 907{@link android.content.pm.PackageManager#queryBroadcastReceivers 908queryBroadcastReceivers()}, for broadcast receivers. 909</p> 910 911 912 913 914