1 page.title=Common Intents 2 page.tags="IntentFilter" 3 @jd:body 4 5 <div id="qv-wrapper"> 6 <div id="qv"> 7 8 <h2>In this document 9 <a href="#" onclick="hideNestedItems('#tocIntents',this);return false;" class="header-toggle"> 10 <span class="more">show more</span> 11 <span class="less" style="display:none">show less</span></a></h2> 12 13 <ol id="tocIntents" class="hide-nested"> 14 <li><a href="#Clock">Alarm Clock</a> 15 <ol> 16 <li><a href="#CreateAlarm">Create an alarm</a></li> 17 <li><a href="#CreateTimer">Create a timer</a></li> 18 <li><a href="#ShowAlarms">Show all alarms</a></li> 19 </ol> 20 </li> 21 <li><a href="#Calendar">Calendar</a> 22 <ol> 23 <li><a href="#AddEvent">Add a calendar event</a></li> 24 </ol> 25 </li> 26 <li><a href="#Camera">Camera</a> 27 <ol> 28 <li><a href="#ImageCapture">Capture a picture or video and return it</a></li> 29 <li><a href="#CameraStill">Start a camera app in still image mode</a></li> 30 <li><a href="#CameraVideo">Start a camera app in video mode</a></li> 31 </ol> 32 </li> 33 <li><a href="#Contacts">Contacts/People App</a> 34 <ol> 35 <li><a href="#PickContact">Select a contact</a></li> 36 <li><a href="#PickContactDat">Select specific contact data</a></li> 37 <li><a href="#ViewContact">View a contact</a></li> 38 <li><a href="#EditContact">Edit an existing contact</a></li> 39 <li><a href="#InsertContact">Insert a contact</a></li> 40 </ol> 41 </li> 42 <li><a href="#Email">Email</a> 43 <ol> 44 <li><a href="#ComposeEmail">Compose an email with optional attachments</a></li> 45 </ol> 46 </li> 47 <li><a href="#Storage">File Storage</a> 48 <ol> 49 <li><a href="#GetFile">Retrieve a specific type of file</a></li> 50 <li><a href="#OpenFile">Open a specific type of file</a></li> 51 </ol> 52 </li> 53 <li><a href="#Fitness">Fitness</a> 54 <ol> 55 <li><a href="#TrackRide">Start/Stop a bike ride</a></li> 56 <li><a href="#TrackRun">Start/Stop a run</a></li> 57 <li><a href="#TrackWorkout">Start/Stop a workout</a></li> 58 <li><a href="#ShowHR">Show heart rate</a></li> 59 <li><a href="#ShowStepCount">Show step count</a></li> 60 </ol> 61 </li> 62 <li><a href="#Local">Local Actions</a> 63 <ol> 64 <li><a href="#CallCar">Call a car</a></li> 65 </ol> 66 </li> 67 <li><a href="#Maps">Maps</a> 68 <ol> 69 <li><a href="#ViewMap">Show a location on a map</a></li> 70 </ol> 71 </li> 72 <li><a href="#Music">Music or Video</a> 73 <ol> 74 <li><a href="#PlayMedia">Play a media file</a></li> 75 <li><a href="#PlaySearch">Play music based on a search query</a></li> 76 </ol> 77 </li> 78 <li><a href="#Phone">Phone</a> 79 <ol> 80 <li><a href="#DialPhone">Initiate a phone call</a></li> 81 </ol> 82 </li> 83 <li><a href="#Settings">Settings</a> 84 <ol> 85 <li><a href="#OpenSettings">Open a specific section of Settings</a></li> 86 </ol> 87 </li> 88 <li><a href="#Messaging">Text Messaging</a> 89 <ol> 90 <li><a href="#SendMessage">Compose an SMS/MMS message with attachment</a></li> 91 </ol> 92 </li> 93 <li><a href="#Browser">Web Browser</a> 94 <ol> 95 <li><a href="#ViewUrl">Load a web URL</a></li> 96 <li><a href="#SearchWeb">Perform a web search</a></li> 97 </ol> 98 </li> 99 <li><a href="#AdbIntents">Verify Intents with the Android Debug Bridge</a></li> 100 <li><a href="#Now">Intents Fired by Google Now</a></li> 101 </ol> 102 103 <h2>See also</h2> 104 <ol> 105 <li><a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent 106 Filters</a></li> 107 </ol> 108 </div> 109 </div> 110 111 <!-- Google Now box styles --> 112 <style type="text/css"> 113 .now-box { 114 border-color: rgb(204,204,204); 115 border-style: solid; 116 border-width: 1px; 117 float: right; 118 margin: 0px 0px 20px 15px; 119 padding: 17px; 120 width: 200px; 121 } 122 .now-box li { 123 font-size: 13px; 124 font-style: italic; 125 margin-top: 0px; 126 } 127 .now-box ul { 128 margin-bottom: 0px; 129 } 130 .now-img { 131 width: 30px; 132 margin-bottom: 0px !important; 133 } 134 .now-img-cont { 135 float: left; 136 margin-right: 10px; 137 } 138 .now-title { 139 font-weight: bold; 140 margin-top: 7px; 141 } 142 .now-list { 143 font-size: 13px; 144 margin-bottom: 10px !important; 145 list-style-type: none; 146 } 147 .now-list li { 148 font-style: italic; 149 } 150 </style> 151 152 <p>An intent allows you to start an activity in another app by describing a simple 153 action you'd like to perform (such as "view a map" or "take a picture") 154 in an {@link android.content.Intent} object. This type of intent is 155 called an <em>implicit</em> intent because it does not specify the app component 156 to start, but instead specifies an <em>action</em> and provides some 157 <em>data</em> with which to perform the action.</p> 158 159 <p>When you call 160 {@link android.content.Context#startActivity startActivity()} or 161 {@link android.app.Activity#startActivityForResult startActivityForResult()} and pass it an 162 implicit intent, the system <a href="{@docRoot}guide/components/intents-filters.html#Resolution" 163 >resolves the intent</a> to an app that can handle the intent 164 and starts its corresponding {@link android.app.Activity}. If there's more than one app 165 that can handle the intent, the system presents the user with a dialog to pick which app 166 to use.</p> 167 168 <p>This page describes several implicit intents that you can use to perform common actions, 169 organized by the type of app that handles the intent. Each section also shows how you can 170 create an <a href="{@docRoot}guide/components/intents-filters.html#Receiving">intent filter</a> to 171 advertise your app's ability to perform the same action.</p> 172 173 <p class="caution"><strong>Caution:</strong> If there are no apps on the device that can receive 174 the implicit intent, your app will crash when it calls {@link android.content.Context#startActivity 175 startActivity()}. To first verify that an app exists to receive the intent, call {@link 176 android.content.Intent#resolveActivity resolveActivity()} on your {@link android.content.Intent} 177 object. If the result is non-null, there is at least one app that can handle the intent and 178 it's safe to call {@link android.content.Context#startActivity startActivity()}. If the result is 179 null, you should not use the intent and, if possible, you should disable the feature that invokes 180 the intent.</p> 181 182 <p>If you're not familiar with how to create intents or intent filters, you should first read 183 <a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>.</p> 184 185 <p>To learn how to fire the intents listed on this page from your development host, see 186 <a href="#AdbIntents">Verify Intents with the Android Debug Bridge</a>.</p> 187 188 <h4>Google Now</h4> 189 190 <p><a href="http://www.google.com/landing/now/">Google Now</a> fires some of the intents listed 191 on this page in response to voice commands. For more information, see 192 <a href="#Now">Intents Fired by Google Now</a>.</p> 193 194 195 196 197 198 199 <h2 id="Clock">Alarm Clock</h2> 200 201 202 <h3 id="CreateAlarm">Create an alarm</h3> 203 204 <!-- Google Now box --> 205 <div class="now-box"> 206 <div class="now-img-cont"> 207 <a href="#Now"> 208 <img src="{@docRoot}guide/components/images/voice-icon.png" class="now-img" width="30" height="30" alt=""/> 209 </a> 210 </div> 211 <p class="now-title">Google Now</p> 212 <ul> 213 <li>"set an alarm for 7 am"</li> 214 </ul> 215 </div> 216 217 <p>To create a new alarm, use the {@link android.provider.AlarmClock#ACTION_SET_ALARM} 218 action and specify alarm details such as the time and message using extras defined below.</p> 219 220 <p class="note"><strong>Note:</strong> Only the hour, minutes, and message extras are available 221 in Android 2.3 (API level 9) and higher. The other extras were added in later versions of the 222 platform.</p> 223 224 <dl> 225 <dt><b>Action</b></dt> 226 <dd>{@link android.provider.AlarmClock#ACTION_SET_ALARM}</dd> 227 228 <dt><b>Data URI</b></dt> 229 <dd>None</dd> 230 231 <dt><b>MIME Type</b></dt> 232 <dd>None 233 </dd> 234 235 <dt><b>Extras</b></dt> 236 <dd> 237 <dl> 238 <dt>{@link android.provider.AlarmClock#EXTRA_HOUR}</dt> 239 <dd>The hour for the alarm.</dd> 240 <dt>{@link android.provider.AlarmClock#EXTRA_MINUTES}</dt> 241 <dd>The minutes for the alarm.</dd> 242 <dt>{@link android.provider.AlarmClock#EXTRA_MESSAGE}</dt> 243 <dd>A custom message to identify the alarm.</dd> 244 <dt>{@link android.provider.AlarmClock#EXTRA_DAYS}</dt> 245 <dd>An {@link java.util.ArrayList} including each week day on which this alarm should 246 be repeated. Each day must be declared with an integer from the {@link java.util.Calendar} 247 class such as {@link java.util.Calendar#MONDAY}. 248 <p>For a one-time alarm, do not specify this extra.</dd> 249 <dt>{@link android.provider.AlarmClock#EXTRA_RINGTONE}</dt> 250 <dd>A {@code content:} URI specifying a ringtone to use with the alarm, or {@link 251 android.provider.AlarmClock#VALUE_RINGTONE_SILENT} for no ringtone. 252 <p>To use the default ringtone, do not specify this extra.</dd> 253 <dt>{@link android.provider.AlarmClock#EXTRA_VIBRATE}</dt> 254 <dd>A boolean specifying whether to vibrate for this alarm.</dd> 255 <dt>{@link android.provider.AlarmClock#EXTRA_SKIP_UI}</dt> 256 <dd>A boolean specifying whether the responding app should skip its UI when setting the alarm. 257 If true, the app should bypass any confirmation UI and simply set the specified alarm.</dd> 258 </dl> 259 </dd> 260 261 262 </dl> 263 264 <p><b>Example intent:</b></p> 265 <pre> 266 public void createAlarm(String message, int hour, int minutes) { 267 Intent intent = new Intent(AlarmClock.ACTION_SET_ALARM) 268 .putExtra(AlarmClock.EXTRA_MESSAGE, message) 269 .putExtra(AlarmClock.EXTRA_HOUR, hour) 270 .putExtra(AlarmClock.EXTRA_MINUTES, minutes); 271 if (intent.resolveActivity(getPackageManager()) != null) { 272 startActivity(intent); 273 } 274 } 275 </pre> 276 277 <div class="note"><strong>Note:</strong> 278 <p>In order to invoke the {@link 279 android.provider.AlarmClock#ACTION_SET_ALARM} intent, your app must have the 280 {@link android.Manifest.permission#SET_ALARM} permission:</p> 281 <pre> 282 <uses-permission android:name="com.android.alarm.permission.SET_ALARM" /> 283 </pre> 284 </div> 285 286 287 <p><b>Example intent filter:</b></p> 288 <pre> 289 <activity ...> 290 <intent-filter> 291 <action android:name="android.intent.action.SET_ALARM" /> 292 <category android:name="android.intent.category.DEFAULT" /> 293 </intent-filter> 294 </activity> 295 </pre> 296 297 298 299 <h3 id="CreateTimer">Create a timer</h3> 300 301 <!-- Google Now box --> 302 <div class="now-box"> 303 <div class="now-img-cont"> 304 <a href="#Now"> 305 <img src="{@docRoot}guide/components/images/voice-icon.png" class="now-img" width="30" height="30" alt=""/> 306 </a> 307 </div> 308 <p class="now-title">Google Now</p> 309 <ul> 310 <li>"set timer for 5 minutes"</li> 311 </ul> 312 </div> 313 314 <p>To create a countdown timer, use the {@link android.provider.AlarmClock#ACTION_SET_TIMER} 315 action and specify timer details such as the duration using extras defined below.</p> 316 317 <p class="note"><strong>Note:</strong> This intent was added 318 in Android 4.4 (API level 19).</p> 319 320 <dl> 321 <dt><b>Action</b></dt> 322 <dd>{@link android.provider.AlarmClock#ACTION_SET_TIMER}</dd> 323 324 <dt><b>Data URI</b></dt> 325 <dd>None</dd> 326 327 <dt><b>MIME Type</b></dt> 328 <dd>None 329 </dd> 330 331 <dt><b>Extras</b></dt> 332 <dd> 333 <dl> 334 <dt>{@link android.provider.AlarmClock#EXTRA_LENGTH}</dt> 335 <dd>The length of the timer in seconds.</dd> 336 <dt>{@link android.provider.AlarmClock#EXTRA_MESSAGE}</dt> 337 <dd>A custom message to identify the timer.</dd> 338 <dt>{@link android.provider.AlarmClock#EXTRA_SKIP_UI}</dt> 339 <dd>A boolean specifying whether the responding app should skip its UI when setting the timer. 340 If true, the app should bypass any confirmation UI and simply start the specified timer.</dd> 341 </dl> 342 </dd> 343 344 345 </dl> 346 347 <p><b>Example intent:</b></p> 348 <pre> 349 public void startTimer(String message, int seconds) { 350 Intent intent = new Intent(AlarmClock.ACTION_SET_TIMER) 351 .putExtra(AlarmClock.EXTRA_MESSAGE, message) 352 .putExtra(AlarmClock.EXTRA_LENGTH, seconds) 353 .putExtra(AlarmClock.EXTRA_SKIP_UI, true); 354 if (intent.resolveActivity(getPackageManager()) != null) { 355 startActivity(intent); 356 } 357 } 358 </pre> 359 360 <div class="note"><strong>Note:</strong> 361 <p>In order to invoke the {@link 362 android.provider.AlarmClock#ACTION_SET_TIMER} intent, your app must have the 363 {@link android.Manifest.permission#SET_ALARM} permission:</p> 364 <pre> 365 <uses-permission android:name="com.android.alarm.permission.SET_ALARM" /> 366 </pre> 367 </div> 368 369 370 <p><b>Example intent filter:</b></p> 371 <pre> 372 <activity ...> 373 <intent-filter> 374 <action android:name="android.intent.action.SET_TIMER" /> 375 <category android:name="android.intent.category.DEFAULT" /> 376 </intent-filter> 377 </activity> 378 </pre> 379 380 381 382 383 384 <h3 id="ShowAlarms">Show all alarms</h3> 385 386 <p>To show the list of alarms, use the {@link android.provider.AlarmClock#ACTION_SHOW_ALARMS} 387 action.</p> 388 389 <p>Although not many apps will invoke this intent (it's primarily used by system apps), 390 any app that behaves as an alarm clock should implement 391 this intent filter and respond by showing the list of current alarms.</p> 392 393 <p class="note"><strong>Note:</strong> This intent was added 394 in Android 4.4 (API level 19).</p> 395 396 <dl> 397 <dt><b>Action</b></dt> 398 <dd>{@link android.provider.AlarmClock#ACTION_SHOW_ALARMS}</dd> 399 400 <dt><b>Data URI</b></dt> 401 <dd>None</dd> 402 403 <dt><b>MIME Type</b></dt> 404 <dd>None 405 </dd> 406 </dl> 407 408 <p><b>Example intent filter:</b></p> 409 <pre> 410 <activity ...> 411 <intent-filter> 412 <action android:name="android.intent.action.SHOW_ALARMS" /> 413 <category android:name="android.intent.category.DEFAULT" /> 414 </intent-filter> 415 </activity> 416 </pre> 417 418 419 420 421 422 423 <h2 id="Calendar">Calendar</h2> 424 425 426 <h3 id="AddEvent">Add a calendar event</h3> 427 428 <p>To add a new event to the user's calendar, use the {@link android.content.Intent#ACTION_INSERT} 429 action and specify the data URI with {@link android.provider.CalendarContract.Events#CONTENT_URI 430 Events.CONTENT_URI}. You can then specify various event details using extras defined below.</p> 431 432 <dl> 433 <dt><b>Action</b></dt> 434 <dd>{@link android.content.Intent#ACTION_INSERT}</dd> 435 436 <dt><b>Data URI</b></dt> 437 <dd>{@link android.provider.CalendarContract.Events#CONTENT_URI 438 Events.CONTENT_URI}</dd> 439 440 <dt><b>MIME Type</b></dt> 441 <dd>{@code "vnd.android.cursor.dir/event"} 442 </dd> 443 444 <dt><b>Extras</b></dt> 445 <dd> 446 <dl> 447 <dt>{@link android.provider.CalendarContract#EXTRA_EVENT_ALL_DAY}</dt> 448 <dd>A boolean specifying whether this is an all-day event.</dd> 449 <dt>{@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME}</dt> 450 <dd>The start time of the event (milliseconds since epoch).</dd> 451 <dt>{@link android.provider.CalendarContract#EXTRA_EVENT_END_TIME}</dt> 452 <dd>The end time of the event (milliseconds since epoch).</dd> 453 <dt>{@link android.provider.CalendarContract.EventsColumns#TITLE}</dt> 454 <dd>The event title.</dd> 455 <dt>{@link android.provider.CalendarContract.EventsColumns#DESCRIPTION}</dt> 456 <dd>The event description.</dd> 457 <dt>{@link android.provider.CalendarContract.EventsColumns#EVENT_LOCATION}</dt> 458 <dd>The event location.</dd> 459 <dt>{@link android.content.Intent#EXTRA_EMAIL}</dt> 460 <dd>A comma-separated list of email addresses that specify the invitees.</dd> 461 </dl> 462 <p>Many more event details can be specified using the constants defined in the 463 {@link android.provider.CalendarContract.EventsColumns} class.</p> 464 </dd> 465 466 467 </dl> 468 469 <p><b>Example intent:</b></p> 470 <pre> 471 public void addEvent(String title, String location, Calendar begin, Calendar end) { 472 Intent intent = new Intent(Intent.ACTION_INSERT) 473 .setData(Events.CONTENT_URI) 474 .putExtra(Events.TITLE, title) 475 .putExtra(Events.EVENT_LOCATION, location) 476 .putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, begin) 477 .putExtra(CalendarContract.EXTRA_EVENT_END_TIME, end); 478 if (intent.resolveActivity(getPackageManager()) != null) { 479 startActivity(intent); 480 } 481 } 482 </pre> 483 484 485 <p><b>Example intent filter:</b></p> 486 <pre> 487 <activity ...> 488 <intent-filter> 489 <action android:name="android.intent.action.INSERT" /> 490 <data android:mimeType="vnd.android.cursor.dir/event" /> 491 <category android:name="android.intent.category.DEFAULT" /> 492 </intent-filter> 493 </activity> 494 </pre> 495 496 497 498 499 500 501 502 503 504 505 506 507 508 <h2 id="Camera">Camera</h2> 509 510 511 512 <h3 id="ImageCapture">Capture a picture or video and return it</h3> 513 514 <p>To open a camera app and receive the resulting photo or video, use the {@link 515 android.provider.MediaStore#ACTION_IMAGE_CAPTURE} or {@link 516 android.provider.MediaStore#ACTION_VIDEO_CAPTURE} action. Also specify the URI location where you'd 517 like the camera to save the photo or video, in the {@link android.provider.MediaStore#EXTRA_OUTPUT} 518 extra.</p> 519 520 521 <dl> 522 <dt><b>Action</b></dt> 523 <dd>{@link android.provider.MediaStore#ACTION_IMAGE_CAPTURE} or<br> 524 {@link android.provider.MediaStore#ACTION_VIDEO_CAPTURE}</dd> 525 526 <dt><b>Data URI Scheme</b></dt> 527 <dd>None</dd> 528 529 <dt><b>MIME Type</b></dt> 530 <dd>None</dd> 531 532 <dt><b>Extras</b></dt> 533 <dd> 534 <dl> 535 <dt>{@link android.provider.MediaStore#EXTRA_OUTPUT}</dt> 536 <dd>The URI location where the camera app should save the photo or 537 video file (as a {@link android.net.Uri} object).</dd> 538 </dl> 539 </dd> 540 </dl> 541 542 <p>When the camera app successfully returns 543 focus to your activity (your app receives the {@link android.app.Activity#onActivityResult 544 onActivityResult()} callback), you can access the photo or video at the URI you specified 545 with the {@link android.provider.MediaStore#EXTRA_OUTPUT} value.</p> 546 547 <p class="note"><strong>Note:</strong> When you use {@link 548 android.provider.MediaStore#ACTION_IMAGE_CAPTURE} to capture a photo, the camera may also return a 549 downscaled copy (a thumbnail) of the photo in the result {@link 550 android.content.Intent}, saved as a {@link android.graphics.Bitmap} in an extra field named 551 <code>"data"</code>.</p> 552 553 554 <p><b>Example intent:</b></p> 555 <pre> 556 static final int REQUEST_IMAGE_CAPTURE = 1; 557 static final Uri mLocationForPhotos; 558 559 public void capturePhoto(String targetFilename) { 560 Intent intent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE); 561 intent.putExtra(MediaStore.EXTRA_OUTPUT, 562 Uri.withAppendedPath(mLocationForPhotos, targetFilename); 563 if (intent.resolveActivity(getPackageManager()) != null) { 564 startActivityForResult(intent, REQUEST_IMAGE_CAPTURE); 565 } 566 } 567 568 @Override 569 protected void onActivityResult(int requestCode, int resultCode, Intent data) { 570 if (requestCode == REQUEST_IMAGE_CAPTURE && resultCode == RESULT_OK) { 571 Bitmap thumbnail = data.getParcelable("data"); 572 // Do other work with full size photo saved in mLocationForPhotos 573 ... 574 } 575 } 576 </pre> 577 578 <p>For more information about how to use this intent to capture a photo, including 579 how to create an appropriate {@link android.net.Uri} for the output location, read 580 <a href="{@docRoot}training/camera/photobasics.html">Taking Photos Simply</a> or 581 <a href="{@docRoot}training/camera/videobasics.html">Taking Videos Simply</a>.</p> 582 583 <p><b>Example intent filter:</b></p> 584 <pre> 585 <activity ...> 586 <intent-filter> 587 <action android:name="android.media.action.IMAGE_CAPTURE" /> 588 <category android:name="android.intent.category.DEFAULT" /> 589 </intent-filter> 590 </activity> 591 </pre> 592 593 <p>When handling this intent, your activity should check for the {@link 594 android.provider.MediaStore#EXTRA_OUTPUT} extra in the incoming {@link android.content.Intent}, 595 then save the captured image or video at the location specified by that extra and call {@link 596 android.app.Activity#setResult(int,Intent) setResult()} with an 597 {@link android.content.Intent} that includes a compressed thumbnail 598 in an extra named <code>"data"</code>.</p> 599 600 601 602 <h3 id="CameraStill">Start a camera app in still image mode</h3> 603 604 <!-- Google Now box --> 605 <div class="now-box"> 606 <div class="now-img-cont"> 607 <a href="#Now"> 608 <img src="{@docRoot}guide/components/images/voice-icon.png" class="now-img" width="30" height="30" alt=""/> 609 </a> 610 </div> 611 <p class="now-title">Google Now</p> 612 <ul> 613 <li>"take a picture"</li> 614 </ul> 615 </div> 616 617 <p>To open a camera app in still image mode, use the {@link 618 android.provider.MediaStore#INTENT_ACTION_STILL_IMAGE_CAMERA} action.</p> 619 620 <dl> 621 <dt><b>Action</b></dt> 622 <dd>{@link android.provider.MediaStore#INTENT_ACTION_STILL_IMAGE_CAMERA}</dd> 623 624 <dt><b>Data URI Scheme</b></dt> 625 <dd>None</dd> 626 627 <dt><b>MIME Type</b></dt> 628 <dd>None</dd> 629 630 <dt><b>Extras</b></dt> 631 <dd>None</dd> 632 </dl> 633 634 635 <p><b>Example intent:</b></p> 636 <pre> 637 public void capturePhoto() { 638 Intent intent = new Intent(MediaStore.INTENT_ACTION_STILL_IMAGE_CAMERA); 639 if (intent.resolveActivity(getPackageManager()) != null) { 640 startActivityForResult(intent); 641 } 642 } 643 </pre> 644 645 <p><b>Example intent filter:</b></p> 646 <pre> 647 <activity ...> 648 <intent-filter> 649 <action android:name="android.media.action.STILL_IMAGE_CAMERA" /> 650 <category android:name="android.intent.category.DEFAULT" /> 651 </intent-filter> 652 </activity> 653 </pre> 654 655 656 657 <h3 id="CameraVideo">Start a camera app in video mode</h3> 658 659 <!-- Google Now box --> 660 <div class="now-box"> 661 <div class="now-img-cont"> 662 <a href="#Now"> 663 <img src="{@docRoot}guide/components/images/voice-icon.png" class="now-img" width="30" height="30" alt=""/> 664 </a> 665 </div> 666 <p class="now-title">Google Now</p> 667 <ul> 668 <li>"record a video"</li> 669 </ul> 670 </div> 671 672 <p>To open a camera app in video mode, use the {@link 673 android.provider.MediaStore#INTENT_ACTION_VIDEO_CAMERA} action.</p> 674 675 <dl> 676 <dt><b>Action</b></dt> 677 <dd>{@link android.provider.MediaStore#INTENT_ACTION_VIDEO_CAMERA}</dd> 678 679 <dt><b>Data URI Scheme</b></dt> 680 <dd>None</dd> 681 682 <dt><b>MIME Type</b></dt> 683 <dd>None</dd> 684 685 <dt><b>Extras</b></dt> 686 <dd>None</dd> 687 </dl> 688 689 690 <p><b>Example intent:</b></p> 691 <pre> 692 public void capturePhoto() { 693 Intent intent = new Intent(MediaStore.INTENT_ACTION_VIDEO_CAMERA); 694 if (intent.resolveActivity(getPackageManager()) != null) { 695 startActivityForResult(intent); 696 } 697 } 698 </pre> 699 700 <p><b>Example intent filter:</b></p> 701 <pre> 702 <activity ...> 703 <intent-filter> 704 <action android:name="android.media.action.VIDEO_CAMERA" /> 705 <category android:name="android.intent.category.DEFAULT" /> 706 </intent-filter> 707 </activity> 708 </pre> 709 710 711 712 713 714 <h2 id="Contacts">Contacts/People App</h2> 715 716 717 <h3 id="PickContact">Select a contact</h3> 718 719 <p>To have the user select a contact and provide your app access to all the contact information, 720 use the {@link android.content.Intent#ACTION_PICK} action and specify the MIME type to 721 {@link android.provider.ContactsContract.Contacts#CONTENT_TYPE 722 Contacts.CONTENT_TYPE}.</p> 723 724 <p>The result {@link android.content.Intent} delivered to your {@link 725 android.app.Activity#onActivityResult onActivityResult()} callback contains the 726 <code>content:</code> URI pointing to the selected contact. The response grants 727 your app temporary permissions to read that contact using the <a 728 href="{@docRoot}guide/topics/providers/contacts-provider.html">Contacts Provider</a> API even if 729 your app does not include the {@link android.Manifest.permission#READ_CONTACTS} permission.</p> 730 731 <p class="note"><strong>Tip:</strong> If you need access to only a specific piece of contact 732 information, such as a phone number or email address, instead see the next section about how to 733 <a href="#PickContactData">select specific contact data</a>.</p> 734 735 <dl> 736 <dt><b>Action</b></dt> 737 <dd>{@link android.content.Intent#ACTION_PICK}</dd> 738 739 <dt><b>Data URI Scheme</b></dt> 740 <dd>None</dd> 741 742 <dt><b>MIME Type</b></dt> 743 <dd>{@link android.provider.ContactsContract.Contacts#CONTENT_TYPE 744 Contacts.CONTENT_TYPE} 745 </dd> 746 </dl> 747 748 <p><b>Example intent:</b></p> 749 <pre> 750 static final int REQUEST_SELECT_CONTACT = 1; 751 752 public void selectContact() { 753 Intent intent = new Intent(Intent.ACTION_PICK); 754 intent.setType(ContactsContract.Contacts.CONTENT_TYPE); 755 if (intent.resolveActivity(getPackageManager()) != null) { 756 startActivityForResult(intent, REQUEST_SELECT_CONTACT); 757 } 758 } 759 760 @Override 761 protected void onActivityResult(int requestCode, int resultCode, Intent data) { 762 if (requestCode == REQUEST_SELECT_CONTACT && resultCode == RESULT_OK) { 763 Uri contactUri = data.getData(); 764 // Do something with the selected contact at contactUri 765 ... 766 } 767 } 768 </pre> 769 770 <p>For information about how to retrieve contact details once you have the contact URI, 771 read <a href="{@docRoot}training/contacts-provider/retrieve-details.html">Retrieving Details 772 for a Contact</a>. Remember, when you retrieve the contact URI with the above intent, you 773 <strong>do not</strong> need the {@link android.Manifest.permission#READ_CONTACTS} permission 774 to read details for that contact.</p> 775 776 777 778 779 <h3 id="PickContactDat">Select specific contact data</h3> 780 781 <p>To have the user select a specific piece of information from a contact, such as 782 a phone number, email address, or other data type, use the 783 {@link android.content.Intent#ACTION_PICK} action and specify the MIME type to one 784 of the content types listed below, such as 785 {@link android.provider.ContactsContract.CommonDataKinds.Phone#CONTENT_TYPE 786 CommonDataKinds.Phone.CONTENT_TYPE} to get the contact's phone number.</p> 787 788 <p>If you need to retrieve only one type of data from a contact, this technique with a 789 {@code CONTENT_TYPE} from the 790 {@link android.provider.ContactsContract.CommonDataKinds} classes is more efficient than 791 using the {@link android.provider.ContactsContract.Contacts#CONTENT_TYPE 792 Contacts.CONTENT_TYPE} (as shown in the previous section) because the result provides you direct 793 access to the desired data without requiring you to perform a more complex query to <a 794 href="{@docRoot}guide/topics/providers/contacts-provider.html">Contacts Provider</a>.</p> 795 796 <p>The result {@link android.content.Intent} delivered to your {@link 797 android.app.Activity#onActivityResult onActivityResult()} callback contains the 798 <code>content:</code> URI pointing to the selected contact data. The response grants 799 your app temporary permissions to read that contact data even if your app does 800 not include the {@link android.Manifest.permission#READ_CONTACTS} permission.</p> 801 802 <dl> 803 <dt><b>Action</b></dt> 804 <dd>{@link android.content.Intent#ACTION_PICK}</dd> 805 806 <dt><b>Data URI Scheme</b></dt> 807 <dd>None</dd> 808 809 <dt><b>MIME Type</b></dt> 810 <dd> 811 <dl> 812 <dt>{@link android.provider.ContactsContract.CommonDataKinds.Phone#CONTENT_TYPE 813 CommonDataKinds.Phone.CONTENT_TYPE}</dt> 814 <dd>Pick from contacts with a phone number.</dd> 815 <dt>{@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_TYPE 816 CommonDataKinds.Email.CONTENT_TYPE}</dt> 817 <dd>Pick from contacts with an email address.</dd> 818 <dt>{@link android.provider.ContactsContract.CommonDataKinds.StructuredPostal#CONTENT_TYPE 819 CommonDataKinds.StructuredPostal.CONTENT_TYPE}</dt> 820 <dd>Pick from contacts with a postal address.</dd> 821 </dl> 822 <p>Or one of many other {@code CONTENT_TYPE} values 823 under {@link android.provider.ContactsContract}.</p> 824 </dd> 825 </dl> 826 827 <p><b>Example intent:</b></p> 828 <pre> 829 static final int REQUEST_SELECT_PHONE_NUMBER = 1; 830 831 public void selectContact() { 832 // Start an activity for the user to pick a phone number from contacts 833 Intent intent = new Intent(Intent.ACTION_PICK); 834 intent.setType(CommonDataKinds.Phone.CONTENT_TYPE); 835 if (intent.resolveActivity(getPackageManager()) != null) { 836 startActivityForResult(intent, REQUEST_SELECT_PHONE_NUMBER); 837 } 838 } 839 840 @Override 841 protected void onActivityResult(int requestCode, int resultCode, Intent data) { 842 if (requestCode == REQUEST_SELECT_PHONE_NUMBER && resultCode == RESULT_OK) { 843 // Get the URI and query the content provider for the phone number 844 Uri contactUri = data.getData(); 845 String[] projection = new String[]{CommonDataKinds.Phone.NUMBER}; 846 Cursor cursor = getContentResolver().query(contactUri, projection, 847 null, null, null); 848 // If the cursor returned is valid, get the phone number 849 if (cursor != null && cursor.moveToFirst()) { 850 int numberIndex = cursor.getColumnIndex(CommonDataKinds.Phone.NUMBER); 851 String number = cursor.getString(numberIndex); 852 // Do something with the phone number 853 ... 854 } 855 } 856 } 857 </pre> 858 859 860 861 862 863 <h3 id="ViewContact">View a contact</h3> 864 865 <p>To display the details for a known contact, use the {@link android.content.Intent#ACTION_VIEW} 866 action and specify the contact with a {@code content:} URI as the intent data.</p> 867 868 <p>There are primarily two ways to initially retrieve the contact's URI:</p> 869 <ul> 870 <li>Use the contact URI returned by the {@link android.content.Intent#ACTION_PICK}, 871 shown in the previous section (this approach does not require any app permissions).</li> 872 <li>Access the list of all contacts directly, as described in <a 873 href="{@docRoot}training/contacts-provider/retrieve-names.html">Retrieving a List of 874 Contacts</a> (this approach requires the {@link android.Manifest.permission#READ_CONTACTS} 875 permission).</li> 876 </ul> 877 878 <dl> 879 <dt><b>Action</b></dt> 880 <dd>{@link android.content.Intent#ACTION_VIEW}</dd> 881 882 <dt><b>Data URI Scheme</b></dt> 883 <dd>{@code content:<URI>}</dd> 884 885 <dt><b>MIME Type</b></dt> 886 <dd>None. The type is inferred from contact URI. 887 </dd> 888 </dl> 889 890 <p><b>Example intent:</b></p> 891 <pre> 892 public void viewContact(Uri contactUri) { 893 Intent intent = new Intent(Intent.ACTION_VIEW, contactUri); 894 if (intent.resolveActivity(getPackageManager()) != null) { 895 startActivity(intent); 896 } 897 } 898 </pre> 899 900 901 902 <h3 id="EditContact">Edit an existing contact</h3> 903 904 <p>To edit a known contact, use the {@link android.content.Intent#ACTION_EDIT} 905 action, specify the contact with a {@code content:} URI 906 as the intent data, and include any known contact information in extras specified by 907 constants in {@link android.provider.ContactsContract.Intents.Insert}.</p> 908 909 <p>There are primarily two ways to initially retrieve the contact URI:</p> 910 <ul> 911 <li>Use the contact URI returned by the {@link android.content.Intent#ACTION_PICK}, 912 shown in the previous section (this approach does not require any app permissions).</li> 913 <li>Access the list of all contacts directly, as described in <a 914 href="{@docRoot}training/contacts-provider/retrieve-names.html">Retrieving a List of 915 Contacts</a> (this approach requires the {@link android.Manifest.permission#READ_CONTACTS} 916 permission).</li> 917 </ul> 918 919 <dl> 920 <dt><b>Action</b></dt> 921 <dd>{@link android.content.Intent#ACTION_EDIT}</dd> 922 923 <dt><b>Data URI Scheme</b></dt> 924 <dd>{@code content:<URI>}</dd> 925 926 <dt><b>MIME Type</b></dt> 927 <dd>The type is inferred from contact URI. 928 </dd> 929 930 <dt><b>Extras</b></dt> 931 <dd>One or more of the extras defined in {@link android.provider.ContactsContract.Intents.Insert} 932 so you can populate fields of the contact details. 933 </dd> 934 </dl> 935 936 <p><b>Example intent:</b></p> 937 <pre> 938 public void editContact(Uri contactUri, String email) { 939 Intent intent = new Intent(Intent.ACTION_EDIT); 940 intent.setData(contactUri); 941 intent.putExtra(Intents.Insert.EMAIL, email); 942 if (intent.resolveActivity(getPackageManager()) != null) { 943 startActivity(intent); 944 } 945 } 946 </pre> 947 948 <p>For more information about how to edit a contact, read <a 949 href="{@docRoot}training/contacts-provider/modify-data.html">Modifying 950 Contacts Using Intents</a>.</p> 951 952 953 954 955 <h3 id="InsertContact">Insert a contact</h3> 956 957 <p>To insert a new contact, use the {@link android.content.Intent#ACTION_INSERT} action, 958 specify {@link android.provider.ContactsContract.Contacts#CONTENT_TYPE Contacts.CONTENT_TYPE} as 959 the MIME type, and include any known contact information in extras specified by 960 constants in {@link android.provider.ContactsContract.Intents.Insert}. 961 962 <dl> 963 <dt><b>Action</b></dt> 964 <dd>{@link android.content.Intent#ACTION_INSERT}</dd> 965 966 <dt><b>Data URI Scheme</b></dt> 967 <dd>None</dd> 968 969 <dt><b>MIME Type</b></dt> 970 <dd>{@link android.provider.ContactsContract.Contacts#CONTENT_TYPE Contacts.CONTENT_TYPE}</dd> 971 972 <dt><b>Extras</b></dt> 973 <dd>One or more of the extras defined in {@link android.provider.ContactsContract.Intents.Insert}. 974 </dd> 975 </dl> 976 977 <p><b>Example intent:</b></p> 978 <pre> 979 public void insertContact(String name, String email) { 980 Intent intent = new Intent(Intent.ACTION_INSERT); 981 intent.setType(Contacts.CONTENT_TYPE); 982 intent.putExtra(Intents.Insert.NAME, name); 983 intent.putExtra(Intents.Insert.EMAIL, email); 984 if (intent.resolveActivity(getPackageManager()) != null) { 985 startActivity(intent); 986 } 987 } 988 </pre> 989 990 <p>For more information about how to insert a contact, read <a 991 href="{@docRoot}training/contacts-provider/modify-data.html">Modifying 992 Contacts Using Intents</a>.</p> 993 994 995 996 997 998 999 1000 <h2 id="Email">Email</h2> 1001 1002 1003 <h3 id="ComposeEmail">Compose an email with optional attachments</h3> 1004 1005 <p>To compose an email, use one of the below actions based on whether you'll include attachments, 1006 and include email details such as the recipient and subject using the extra keys listed below.</p> 1007 1008 <dl> 1009 <dt><b>Action</b></dt> 1010 <dd>{@link android.content.Intent#ACTION_SENDTO} (for no attachment) or<br> 1011 {@link android.content.Intent#ACTION_SEND} (for one attachment) or<br> 1012 {@link android.content.Intent#ACTION_SEND_MULTIPLE} (for multiple attachments)</dd> 1013 1014 <dt><b>Data URI Scheme</b></dt> 1015 <dd>None</dd> 1016 1017 <dt><b>MIME Type</b></dt> 1018 <dd> 1019 <dl> 1020 <dt>{@link org.apache.http.protocol.HTTP#PLAIN_TEXT_TYPE} ("text/plain") 1021 <dt><code>"*/*"</code> 1022 </dl> 1023 </dd> 1024 1025 <dt><b>Extras</b></dt> 1026 <dd> 1027 <dl> 1028 <dt>{@link android.content.Intent#EXTRA_EMAIL Intent.EXTRA_EMAIL}</dt> 1029 <dd>A string array of all "To" recipient email addresses.</dd> 1030 <dt>{@link android.content.Intent#EXTRA_CC Intent.EXTRA_CC}</dt> 1031 <dd>A string array of all "CC" recipient email addresses.</dd> 1032 <dt>{@link android.content.Intent#EXTRA_BCC Intent.EXTRA_BCC}</dt> 1033 <dd>A string array of all "BCC" recipient email addresses.</dd> 1034 <dt>{@link android.content.Intent#EXTRA_SUBJECT Intent.EXTRA_SUBJECT}</dt> 1035 <dd>A string with the email subject.</dd> 1036 <dt>{@link android.content.Intent#EXTRA_TEXT Intent.EXTRA_TEXT}</dt> 1037 <dd>A string with the body of the email.</dd> 1038 <dt>{@link android.content.Intent#EXTRA_STREAM Intent.EXTRA_STREAM}</dt> 1039 <dd>A {@link android.net.Uri} pointing to the attachment. If using the 1040 {@link android.content.Intent#ACTION_SEND_MULTIPLE} action, this should instead 1041 be an {@link java.util.ArrayList} containing multiple {@link android.net.Uri} objects.</dd> 1042 </dl> 1043 </dd> 1044 1045 </dl> 1046 1047 1048 <p><b>Example intent:</b></p> 1049 <pre> 1050 public void composeEmail(String[] addresses, String subject, Uri attachment) { 1051 Intent intent = new Intent(Intent.ACTION_SEND); 1052 intent.setType("*/*"); 1053 intent.putExtra(Intent.EXTRA_EMAIL, addresses); 1054 intent.putExtra(Intent.EXTRA_SUBJECT, subject); 1055 intent.putExtra(Intent.EXTRA_STREAM, attachment); 1056 if (intent.resolveActivity(getPackageManager()) != null) { 1057 startActivity(intent); 1058 } 1059 } 1060 </pre> 1061 1062 <p>If you want to ensure that your intent is handled only by an email app (and not other 1063 text messaging or social apps), then use the {@link android.content.Intent#ACTION_SENDTO} action 1064 and include the {@code "mailto:"} data scheme. For example:</p> 1065 1066 <pre> 1067 public void composeEmail(String[] addresses, String subject) { 1068 Intent intent = new Intent(Intent.ACTION_SENDTO); 1069 intent.setData(Uri.parse("mailto:")); // only email apps should handle this 1070 intent.putExtra(Intent.EXTRA_EMAIL, addresses); 1071 intent.putExtra(Intent.EXTRA_SUBJECT, subject); 1072 if (intent.resolveActivity(getPackageManager()) != null) { 1073 startActivity(intent); 1074 } 1075 } 1076 </pre> 1077 1078 1079 <p><b>Example intent filter:</b></p> 1080 <pre> 1081 <activity ...> 1082 <intent-filter> 1083 <action android:name="android.intent.action.SEND" /> 1084 <data android:type="*/*" /> 1085 <category android:name="android.intent.category.DEFAULT" /> 1086 </intent-filter> 1087 <intent-filter> 1088 <action android:name="android.intent.action.SENDTO" /> 1089 <data android:scheme="mailto" /> 1090 <category android:name="android.intent.category.DEFAULT" /> 1091 </intent-filter> 1092 </activity> 1093 </pre> 1094 1095 1096 1097 1098 1099 1100 1101 <h2 id="Storage">File Storage</h2> 1102 1103 1104 1105 <h3 id="GetFile">Retrieve a specific type of file</h3> 1106 1107 <p>To request that the user select a file such as a document or photo and return a reference to 1108 your app, use the {@link android.content.Intent#ACTION_GET_CONTENT} action and specify your desired 1109 MIME type. The file reference returned to your app is transient to your activity's current 1110 lifecycle, so if you want to access it later you must import a copy that you can read later. 1111 This intent also allows the user to create a new file in the process (for 1112 example, instead of selecting an existing photo, the user can capture a new photo with the camera). 1113 </p> 1114 1115 <p>The result intent delivered to your {@link android.app.Activity#onActivityResult 1116 onActivityResult()} method includes data with a URI pointing to the file. 1117 The URI could be anything, such as an {@code http:} URI, {@code file:} URI, or {@code content:} 1118 URI. However, if you'd like to restrict selectable files to only those that are accessible 1119 from a content provider (a {@code content:} URI) and that are available as a file stream with {@link 1120 android.content.ContentResolver#openFileDescriptor openFileDescriptor()}, you should add 1121 the {@link android.content.Intent#CATEGORY_OPENABLE} category to your intent.</p> 1122 1123 <p>On Android 4.3 (API level 18) and higher, 1124 you can also allow the user to select multiple files by adding 1125 {@link android.content.Intent#EXTRA_ALLOW_MULTIPLE} to the intent, set to {@code true}. 1126 You can then access each of the selected files in a {@link android.content.ClipData} 1127 object returned by {@link android.content.Intent#getClipData()}.</p> 1128 1129 1130 <dl> 1131 <dt><b>Action</b></dt> 1132 <dd>{@link android.content.Intent#ACTION_GET_CONTENT}</dd> 1133 1134 <dt><b>Data URI Scheme</b></dt> 1135 <dd>None</dd> 1136 1137 <dt><b>MIME Type</b></dt> 1138 <dd>The MIME type corresponding to the file type the user should select. 1139 </dd> 1140 1141 <dt><b>Extras</b></dt> 1142 <dd> 1143 <dl> 1144 <dt>{@link android.content.Intent#EXTRA_ALLOW_MULTIPLE} 1145 <dd>A boolean declaring whether the user can select more than one file at a time. 1146 </dd> 1147 <dt>{@link android.content.Intent#EXTRA_LOCAL_ONLY} 1148 <dd>A boolean that declares whether the returned file must be available directly from 1149 the device, rather than requiring a download from a remote service. 1150 </dd> 1151 </dl> 1152 </dd> 1153 1154 <dt><b>Category</b> (optional)</dt> 1155 <dd> 1156 <dl> 1157 <dt>{@link android.content.Intent#CATEGORY_OPENABLE}</dt> 1158 <dd>To return only "openable" files that can be represented as a file stream 1159 with {@link android.content.ContentResolver#openFileDescriptor openFileDescriptor()}.</dd> 1160 </dl> 1161 </dd> 1162 1163 </dl> 1164 1165 <p><b>Example intent to get a photo:</b></p> 1166 <pre> 1167 static final int REQUEST_IMAGE_GET = 1; 1168 1169 public void selectImage() { 1170 Intent intent = new Intent(Intent.ACTION_GET_CONTENT); 1171 intent.setType("image/*"); 1172 if (intent.resolveActivity(getPackageManager()) != null) { 1173 startActivityForResult(intent, REQUEST_IMAGE_GET); 1174 } 1175 } 1176 1177 @Override 1178 protected void onActivityResult(int requestCode, int resultCode, Intent data) { 1179 if (requestCode == REQUEST_IMAGE_GET && resultCode == RESULT_OK) { 1180 Bitmap thumbnail = data.getParcelable("data"); 1181 Uri fullPhotoUri = data.getData(); 1182 // Do work with photo saved at fullPhotoUri 1183 ... 1184 } 1185 } 1186 </pre> 1187 1188 <p><b>Example intent filter to return a photo:</b></p> 1189 <pre> 1190 <activity ...> 1191 <intent-filter> 1192 <action android:name="android.intent.action.GET_CONTENT" /> 1193 <data android:type="image/*" /> 1194 <category android:name="android.intent.category.DEFAULT" /> 1195 <!-- The OPENABLE category declares that the returned file is accessible 1196 from a content provider that supports {@link android.provider.OpenableColumns} 1197 and {@link android.content.ContentResolver#openFileDescriptor ContentResolver.openFileDescriptor()} --> 1198 <category android:name="android.intent.category.OPENABLE" /> 1199 </intent-filter> 1200 </activity> 1201 </pre> 1202 1203 1204 1205 1206 1207 1208 <h3 id="OpenFile">Open a specific type of file</h3> 1209 1210 <p>Instead of retrieving a copy of a file that you must import to your app 1211 (by using the {@link android.content.Intent#ACTION_GET_CONTENT} action), when running on Android 1212 4.4 or higher, you can instead request to <em>open</em> a file that's managed by another app by 1213 using the {@link android.content.Intent#ACTION_OPEN_DOCUMENT} action and specifying a MIME type. 1214 To also allow the user to instead create a new document that your app can write to, use the {@link 1215 android.content.Intent#ACTION_CREATE_DOCUMENT} action instead. For example, instead of 1216 selecting from existing PDF documents, the {@link android.content.Intent#ACTION_CREATE_DOCUMENT} 1217 intent allows users to select where they'd like to create a new document (within another app 1218 that manages the document's storage)—your app then receives the URI location of where it 1219 can write the new document.</p> 1220 1221 <p>Whereas the intent delivered to your {@link android.app.Activity#onActivityResult 1222 onActivityResult()} method from the {@link android.content.Intent#ACTION_GET_CONTENT} action may 1223 return a URI of any type, the result intent from {@link android.content.Intent#ACTION_OPEN_DOCUMENT} 1224 and {@link android.content.Intent#ACTION_CREATE_DOCUMENT} always specify the chosen file as a {@code 1225 content:} URI that's backed by a {@link android.provider.DocumentsProvider}. You can open the 1226 file with {@link android.content.ContentResolver#openFileDescriptor openFileDescriptor()} and 1227 query its details using columns from {@link android.provider.DocumentsContract.Document}.</p> 1228 1229 <p>The returned URI grants your app long-term read access to the file (also possibly 1230 with write access). So the {@link android.content.Intent#ACTION_OPEN_DOCUMENT} action is 1231 particularly useful (instead of using {@link android.content.Intent#ACTION_GET_CONTENT}) 1232 when you want to read an existing file without making a copy into your app, 1233 or when you want to open and edit a file in place.</p> 1234 1235 <p>You can also allow the user to select multiple files by adding 1236 {@link android.content.Intent#EXTRA_ALLOW_MULTIPLE} to the intent, set to {@code true}. 1237 If the user selects just one item, then you can retrieve the item from {@link 1238 android.content.Intent#getData()}. If the user selects more than one item, then {@link 1239 android.content.Intent#getData()} returns null and you must instead 1240 retrieve each item from a {@link android.content.ClipData} 1241 object that is returned by {@link android.content.Intent#getClipData()}.</p> 1242 1243 <p class="note"><strong>Note:</strong> Your intent <strong>must</strong> specify a MIME type and 1244 <strong>must</strong> declare the {@link android.content.Intent#CATEGORY_OPENABLE} category. If 1245 appropriate, you can specify more than one MIME type by adding an array of MIME types with the 1246 {@link android.content.Intent#EXTRA_MIME_TYPES} extra—if you do so, you must set the 1247 primary MIME type in {@link android.content.Intent#setType setType()} to {@code "*/*"}.</p> 1248 1249 <dl> 1250 <dt><b>Action</b></dt> 1251 <dd>{@link android.content.Intent#ACTION_OPEN_DOCUMENT} or<br/> 1252 {@link android.content.Intent#ACTION_CREATE_DOCUMENT}</dd> 1253 1254 <dt><b>Data URI Scheme</b></dt> 1255 <dd>None</dd> 1256 1257 <dt><b>MIME Type</b></dt> 1258 <dd>The MIME type corresponding to the file type the user should select. 1259 </dd> 1260 1261 <dt><b>Extras</b></dt> 1262 <dd> 1263 <dl> 1264 <dt>{@link android.content.Intent#EXTRA_MIME_TYPES} 1265 <dd>An array of MIME types corresponding to the types of files your app is 1266 requesting. When you use this extra, you must set the primary MIME type in 1267 {@link android.content.Intent#setType setType()} to {@code "*/*"}.</dd> 1268 <dt>{@link android.content.Intent#EXTRA_ALLOW_MULTIPLE} 1269 <dd>A boolean that declares whether the user can select more than one file at a time. 1270 </dd> 1271 <dt>{@link android.content.Intent#EXTRA_TITLE} 1272 <dd>For use with {@link android.content.Intent#ACTION_CREATE_DOCUMENT} to specify 1273 an initial file name. 1274 </dd> 1275 <dt>{@link android.content.Intent#EXTRA_LOCAL_ONLY} 1276 <dd>A boolean that declares whether the returned file must be available directly from 1277 the device, rather than requiring a download from a remote service. 1278 </dd> 1279 </dl> 1280 </dd> 1281 1282 <dt><b>Category</b></dt> 1283 <dd> 1284 <dl> 1285 <dt>{@link android.content.Intent#CATEGORY_OPENABLE}</dt> 1286 <dd>To return only "openable" files that can be represented as a file stream 1287 with {@link android.content.ContentResolver#openFileDescriptor openFileDescriptor()}.</dd> 1288 </dl> 1289 </dd> 1290 1291 </dl> 1292 1293 <p><b>Example intent to get a photo:</b></p> 1294 <pre> 1295 static final int REQUEST_IMAGE_OPEN = 1; 1296 1297 public void selectImage() { 1298 Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT); 1299 intent.setType("image/*"); 1300 intent.addCategory(Intent.CATEGORY_OPENABLE); 1301 // Only the system receives the ACTION_OPEN_DOCUMENT, so no need to test. 1302 startActivityForResult(intent, REQUEST_IMAGE_OPEN); 1303 } 1304 1305 @Override 1306 protected void onActivityResult(int requestCode, int resultCode, Intent data) { 1307 if (requestCode == REQUEST_IMAGE_OPEN && resultCode == RESULT_OK) { 1308 Uri fullPhotoUri = data.getData(); 1309 // Do work with full size photo saved at fullPhotoUri 1310 ... 1311 } 1312 } 1313 </pre> 1314 1315 <p>Third party apps cannot actually respond to an intent with the 1316 {@link android.content.Intent#ACTION_OPEN_DOCUMENT} action. Instead, the system receives this 1317 intent and displays all the files available from various apps in a unified user interface.</p> 1318 1319 <p>To provide your app's files in this UI and allow other apps to open them, you must implement 1320 a {@link android.provider.DocumentsProvider} and include an intent filter for 1321 {@link android.provider.DocumentsContract#PROVIDER_INTERFACE} 1322 ({@code "android.content.action.DOCUMENTS_PROVIDER"}). For example: 1323 1324 <pre> 1325 <provider ... 1326 android:grantUriPermissions="true" 1327 android:exported="true" 1328 android:permission="android.permission.MANAGE_DOCUMENTS"> 1329 <intent-filter> 1330 <action android:name="android.content.action.DOCUMENTS_PROVIDER" /> 1331 </intent-filter> 1332 </provider> 1333 </pre> 1334 1335 <p>For more information about how to make the files managed by your app openable from other apps, 1336 read the <a href="{@docRoot}guide/topics/providers/document-provider.html">Storage Access 1337 Framework</a> guide.</p> 1338 1339 1340 1341 1342 1343 1344 1345 1346 <h2 id="Fitness">Fitness</h2> 1347 1348 <h3 id="TrackRide">Start/Stop a bike ride</h3> 1349 1350 <!-- Google Now box --> 1351 <div class="now-box"> 1352 <div class="now-img-cont"> 1353 <a href="#Now"> 1354 <img src="{@docRoot}guide/components/images/voice-icon.png" class="now-img" width="30" height="30" alt=""/> 1355 </a> 1356 </div> 1357 <p class="now-title">Google Now</p> 1358 <ul> 1359 <li>"start cycling"</li> 1360 <li>"start my bike ride"</li> 1361 <li>"stop cycling"</li> 1362 </ul> 1363 </div> 1364 1365 <p>To track a bike ride, use the <code>"vnd.google.fitness.TRACK"</code> action with the 1366 <code>"vnd.google.fitness.activity/biking"</code> MIME type and set the <code>"actionStatus"</code> 1367 extra to <code>"ActiveActionStatus"</code> when starting and to <code>"CompletedActionStatus"</code> 1368 when stopping.</p> 1369 1370 <dl> 1371 <dt><b>Action</b></dt> 1372 <dd><code>"vnd.google.fitness.TRACK"</code><dd> 1373 1374 <dt><b>Data URI</b></dt> 1375 <dd>None</dd> 1376 1377 <dt><b>MIME Type</b></dt> 1378 <dd><code>"vnd.google.fitness.activity/biking"</code></dd> 1379 1380 <dt><b>Extras</b></dt> 1381 <dd> 1382 <dl> 1383 <dt><code>"actionStatus"</code></dt> 1384 <dd>A string with the value <code>"ActiveActionStatus"</code> when starting and 1385 <code>"CompletedActionStatus"</code> when stopping.</dd> 1386 </dl> 1387 </dd> 1388 </dl> 1389 1390 1391 <p><b>Example intent:</b></p> 1392 <pre> 1393 public void startBikeRide() { 1394 Intent intent = new Intent("vnd.google.fitness.TRACK") 1395 .setType("vnd.google.fitness.activity/biking") 1396 .putExtra("actionStatus", "ActiveActionStatus"); 1397 if (intent.resolveActivity(getPackageManager()) != null) { 1398 startActivity(intent); 1399 } 1400 } 1401 </pre> 1402 1403 1404 <p><b>Example intent filter:</b></p> 1405 <pre> 1406 <activity ...> 1407 <intent-filter> 1408 <action android:name="vnd.google.fitness.TRACK" /> 1409 <data android:mimeType="vnd.google.fitness.activity/biking" /> 1410 <category android:name="android.intent.category.DEFAULT" /> 1411 </intent-filter> 1412 </activity> 1413 </pre> 1414 1415 1416 1417 1418 1419 <h3 id="TrackRun">Start/Stop a run</h3> 1420 1421 <!-- Google Now box --> 1422 <div class="now-box"> 1423 <div class="now-img-cont"> 1424 <a href="#Now"> 1425 <img src="{@docRoot}guide/components/images/voice-icon.png" class="now-img" width="30" height="30" alt=""/> 1426 </a> 1427 </div> 1428 <p class="now-title">Google Now</p> 1429 <ul> 1430 <li>"track my run"</li> 1431 <li>"start running"</li> 1432 <li>"stop running"</li> 1433 </ul> 1434 </div> 1435 1436 <p>To track a run, use the <code>"vnd.google.fitness.TRACK"</code> action with the 1437 <code>"vnd.google.fitness.activity/running"</code> MIME type and set the <code>"actionStatus"</code> 1438 extra to <code>"ActiveActionStatus"</code> when starting and to <code>"CompletedActionStatus"</code> 1439 when stopping.</p> 1440 1441 <dl> 1442 <dt><b>Action</b></dt> 1443 <dd><code>"vnd.google.fitness.TRACK"</code><dd> 1444 1445 <dt><b>Data URI</b></dt> 1446 <dd>None</dd> 1447 1448 <dt><b>MIME Type</b></dt> 1449 <dd><code>"vnd.google.fitness.activity/running"</code></dd> 1450 1451 <dt><b>Extras</b></dt> 1452 <dd> 1453 <dl> 1454 <dt><code>"actionStatus"</code></dt> 1455 <dd>A string with the value <code>"ActiveActionStatus"</code> when starting and 1456 <code>"CompletedActionStatus"</code> when stopping.</dd> 1457 </dl> 1458 </dd> 1459 </dl> 1460 1461 1462 <p><b>Example intent:</b></p> 1463 <pre> 1464 public void startRun() { 1465 Intent intent = new Intent("vnd.google.fitness.TRACK") 1466 .setType("vnd.google.fitness.activity/running") 1467 .putExtra("actionStatus", "ActiveActionStatus"); 1468 if (intent.resolveActivity(getPackageManager()) != null) { 1469 startActivity(intent); 1470 } 1471 } 1472 </pre> 1473 1474 1475 <p><b>Example intent filter:</b></p> 1476 <pre> 1477 <activity ...> 1478 <intent-filter> 1479 <action android:name="vnd.google.fitness.TRACK" /> 1480 <data android:mimeType="vnd.google.fitness.activity/running" /> 1481 <category android:name="android.intent.category.DEFAULT" /> 1482 </intent-filter> 1483 </activity> 1484 </pre> 1485 1486 1487 1488 1489 <h3 id="TrackWorkout">Start/Stop a workout</h3> 1490 1491 <!-- Google Now box --> 1492 <div class="now-box"> 1493 <div class="now-img-cont"> 1494 <a href="#Now"> 1495 <img src="{@docRoot}guide/components/images/voice-icon.png" class="now-img" width="30" height="30" alt=""/> 1496 </a> 1497 </div> 1498 <p class="now-title">Google Now</p> 1499 <ul> 1500 <li>"start a workout"</li> 1501 <li>"track my workout"</li> 1502 <li>"stop workout"</li> 1503 </ul> 1504 </div> 1505 1506 <p>To track a workout, use the <code>"vnd.google.fitness.TRACK"</code> action with the 1507 <code>"vnd.google.fitness.activity/other"</code> MIME type and set the <code>"actionStatus"</code> 1508 extra to <code>"ActiveActionStatus"</code> when starting and to <code>"CompletedActionStatus"</code> 1509 when stopping.</p> 1510 1511 <dl> 1512 <dt><b>Action</b></dt> 1513 <dd><code>"vnd.google.fitness.TRACK"</code><dd> 1514 1515 <dt><b>Data URI</b></dt> 1516 <dd>None</dd> 1517 1518 <dt><b>MIME Type</b></dt> 1519 <dd><code>"vnd.google.fitness.activity/other"</code></dd> 1520 1521 <dt><b>Extras</b></dt> 1522 <dd> 1523 <dl> 1524 <dt><code>"actionStatus"</code></dt> 1525 <dd>A string with the value <code>"ActiveActionStatus"</code> when starting and 1526 <code>"CompletedActionStatus"</code> when stopping.</dd> 1527 </dl> 1528 </dd> 1529 </dl> 1530 1531 1532 <p><b>Example intent:</b></p> 1533 <pre> 1534 public void startWorkout() { 1535 Intent intent = new Intent("vnd.google.fitness.TRACK") 1536 .setType("vnd.google.fitness.activity/other") 1537 .putExtra("actionStatus", "ActiveActionStatus"); 1538 if (intent.resolveActivity(getPackageManager()) != null) { 1539 startActivity(intent); 1540 } 1541 } 1542 </pre> 1543 1544 1545 <p><b>Example intent filter:</b></p> 1546 <pre> 1547 <activity ...> 1548 <intent-filter> 1549 <action android:name="vnd.google.fitness.TRACK" /> 1550 <data android:mimeType="vnd.google.fitness.activity/other" /> 1551 <category android:name="android.intent.category.DEFAULT" /> 1552 </intent-filter> 1553 </activity> 1554 </pre> 1555 1556 1557 1558 1559 <h3 id="ShowHeartRate">Show heart rate</h3> 1560 1561 <!-- Google Now box --> 1562 <div class="now-box"> 1563 <div class="now-img-cont"> 1564 <a href="#Now"> 1565 <img src="{@docRoot}guide/components/images/voice-icon.png" class="now-img" width="30" height="30" alt=""/> 1566 </a> 1567 </div> 1568 <p class="now-title">Google Now</p> 1569 <ul> 1570 <li>"what's my heart rate?"</li> 1571 <li>"what's my bpm?"</li> 1572 </ul> 1573 </div> 1574 1575 <p>To show the user's heart rate, use the <code>"vnd.google.fitness.VIEW"</code> action with the 1576 <code>"vnd.google.fitness.data_type<br/>/com.google.heart_rate.bpm"</code> MIME type.</p> 1577 1578 <dl> 1579 <dt><b>Action</b></dt> 1580 <dd><code>"vnd.google.fitness.VIEW"</code><dd> 1581 1582 <dt><b>Data URI</b></dt> 1583 <dd>None</dd> 1584 1585 <dt><b>MIME Type</b></dt> 1586 <dd><code>"vnd.google.fitness.data_type/com.google.heart_rate.bpm"</code></dd> 1587 1588 <dt><b>Extras</b></dt> 1589 <dd>None</dd> 1590 </dl> 1591 1592 1593 <p><b>Example intent:</b></p> 1594 <pre> 1595 public void showHR() { 1596 Intent intent = new Intent("vnd.google.fitness.VIEW") 1597 .setType("vnd.google.fitness.data_type/com.google.heart_rate.bpm"); 1598 if (intent.resolveActivity(getPackageManager()) != null) { 1599 startActivity(intent); 1600 } 1601 } 1602 </pre> 1603 1604 1605 <p><b>Example intent filter:</b></p> 1606 <pre> 1607 <activity ...> 1608 <intent-filter> 1609 <action android:name="vnd.google.fitness.VIEW" /> 1610 <data android:mimeType="vnd.google.fitness.data_type/com.google.heart_rate.bpm" /> 1611 <category android:name="android.intent.category.DEFAULT" /> 1612 </intent-filter> 1613 </activity> 1614 </pre> 1615 1616 1617 1618 1619 1620 <h3 id="ShowStepCount">Show step count</h3> 1621 1622 <!-- Google Now box --> 1623 <div class="now-box"> 1624 <div class="now-img-cont"> 1625 <a href="#Now"> 1626 <img src="{@docRoot}guide/components/images/voice-icon.png" class="now-img" width="30" height="30" alt=""/> 1627 </a> 1628 </div> 1629 <p class="now-title">Google Now</p> 1630 <ul> 1631 <li>"how many steps have I taken?"</li> 1632 <li>"what's my step count?"</li> 1633 </ul> 1634 </div> 1635 1636 <p>To show the user's step count, use the <code>"vnd.google.fitness.VIEW"</code> action with the 1637 <code>"vnd.google.fitness.data_type<br/>/com.google.step_count.cumulative"</code> MIME type.</p> 1638 1639 <dl> 1640 <dt><b>Action</b></dt> 1641 <dd><code>"vnd.google.fitness.VIEW"</code><dd> 1642 1643 <dt><b>Data URI</b></dt> 1644 <dd>None</dd> 1645 1646 <dt><b>MIME Type</b></dt> 1647 <dd><code>"vnd.google.fitness.data_type/com.google.step_count.cumulative"</code></dd> 1648 1649 <dt><b>Extras</b></dt> 1650 <dd>None</dd> 1651 </dl> 1652 1653 1654 <p><b>Example intent:</b></p> 1655 <pre> 1656 public void showStepCount() { 1657 Intent intent = new Intent("vnd.google.fitness.VIEW") 1658 .setType("vnd.google.fitness.data_type/com.google.step_count.cumulative"); 1659 if (intent.resolveActivity(getPackageManager()) != null) { 1660 startActivity(intent); 1661 } 1662 } 1663 </pre> 1664 1665 1666 <p><b>Example intent filter:</b></p> 1667 <pre> 1668 <activity ...> 1669 <intent-filter> 1670 <action android:name="vnd.google.fitness.VIEW" /> 1671 <data android:mimeType="vnd.google.fitness.data_type/com.google.step_count.cumulative" /> 1672 <category android:name="android.intent.category.DEFAULT" /> 1673 </intent-filter> 1674 </activity> 1675 </pre> 1676 1677 1678 1679 1680 1681 1682 1683 1684 <h2 id="Local">Local Actions</h2> 1685 1686 <h3 id="CallCar">Call a car</h3> 1687 1688 <!-- Google Now box --> 1689 <div class="now-box"> 1690 <div class="now-img-cont"> 1691 <a href="#Now"> 1692 <img src="{@docRoot}guide/components/images/voice-icon.png" class="now-img" width="30" height="30" alt=""/> 1693 </a> 1694 </div> 1695 <p class="now-title">Google Now</p> 1696 <ul> 1697 <li>"get me a taxi"</li> 1698 <li>"call me a car"</li> 1699 </ul> 1700 <p style="font-size:13px;margin-bottom:0px;margin-top:10px">(Android Wear only)</p> 1701 </div> 1702 1703 <p>To call a taxi, use the 1704 <a href="{@docRoot}com/google/android/gms/actions/ReserveIntents.html#ACTION_RESERVE_TAXI_RESERVATION"><code>ACTION_RESERVE_TAXI_RESERVATION</code></a> 1705 action.</p> 1706 1707 <p class="note"><strong>Note:</strong> Apps must ask for confirmation from the user 1708 before completing the action.</p> 1709 1710 <dl> 1711 <dt><b>Action</b></dt> 1712 <dd><a href="{@docRoot}com/google/android/gms/actions/ReserveIntents.html#ACTION_RESERVE_TAXI_RESERVATION"><code>ACTION_RESERVE_TAXI_RESERVATION</code></a></dd> 1713 1714 <dt><b>Data URI</b></dt> 1715 <dd>None</dd> 1716 1717 <dt><b>MIME Type</b></dt> 1718 <dd>None</dd> 1719 1720 <dt><b>Extras</b></dt> 1721 <dd>None</dd> 1722 </dl> 1723 1724 1725 <p><b>Example intent:</b></p> 1726 <pre> 1727 public void callCar() { 1728 Intent intent = new Intent(ReserveIntents.ACTION_RESERVE_TAXI_RESERVATION); 1729 if (intent.resolveActivity(getPackageManager()) != null) { 1730 startActivity(intent); 1731 } 1732 } 1733 </pre> 1734 1735 1736 <p><b>Example intent filter:</b></p> 1737 <pre> 1738 <activity ...> 1739 <intent-filter> 1740 <action android:name="com.google.android.gms.actions.RESERVE_TAXI_RESERVATION" /> 1741 <category android:name="android.intent.category.DEFAULT" /> 1742 </intent-filter> 1743 </activity> 1744 </pre> 1745 1746 1747 1748 1749 1750 1751 1752 1753 <h2 id="Maps">Maps</h2> 1754 1755 <h3 id="ViewMap">Show a location on a map</h3> 1756 1757 <p>To open a map, use the {@link android.content.Intent#ACTION_VIEW} action and specify 1758 the location information in the intent data with one of the schemes defined below.</p> 1759 1760 <dl> 1761 <dt><b>Action</b></dt> 1762 <dd>{@link android.content.Intent#ACTION_VIEW}</dd> 1763 1764 <dt><b>Data URI Scheme</b></dt> 1765 <dd> 1766 <dl> 1767 <dt><code>geo:<em>latitude</em>,<em>longitude</em></code></dt> 1768 <dd>Show the map at the given longitude and latitude. 1769 <p>Example: <code>"geo:47.6,-122.3"</code> 1770 </dd> 1771 <dt><code>geo:<em>latitude</em>,<em>longitude</em>?z=<em>zoom</em></code></dt> 1772 <dd>Show the map at the given longitude and latitude at a certain zoom level. A zoom level of 1773 1 shows the whole Earth, centered at the given <em>lat</em>,<em>lng</em>. The highest 1774 (closest) zoom level is 23. 1775 <p>Example: <code>"geo:47.6,-122.3?z=11"</code> 1776 </dd> 1777 <dt><code>geo:0,0?q=lat,lng(label)</code></dt> 1778 <dd>Show the map at the given longitude and latitude with a string label. 1779 <p>Example: <code>"geo:0,0?q=34.99,-106.61(Treasure)"</code> 1780 </dd> 1781 <dt><code>geo:0,0?q=my+street+address</code></dt> 1782 <dd>Show the location for "my street address" (may be a specific address or location query). 1783 <p>Example: <code>"geo:0,0?q=1600+Amphitheatre+Parkway%2C+CA"</code></p> 1784 <p class="note"><strong>Note:</strong> All strings passed in the {@code geo} URI must 1785 be encoded. For example, the string {@code 1st & Pike, Seattle} should become 1786 {@code 1st%20%26%20Pike%2C%20Seattle}. Spaces in the string can be encoded with 1787 {@code %20} or replaced with the plus sign ({@code +}).</p> 1788 </dd> 1789 </dl> 1790 </dd> 1791 1792 <dt><b>MIME Type</b></dt> 1793 <dd>None</dd> 1794 1795 </dl> 1796 1797 <p><b>Example intent:</b></p> 1798 <pre> 1799 public void showMap(Uri geoLocation) { 1800 Intent intent = new Intent(Intent.ACTION_VIEW); 1801 intent.setData(geoLocation); 1802 if (intent.resolveActivity(getPackageManager()) != null) { 1803 startActivity(intent); 1804 } 1805 } 1806 </pre> 1807 1808 <p><b>Example intent filter:</b></p> 1809 <pre> 1810 <activity ...> 1811 <intent-filter> 1812 <action android:name="android.intent.action.VIEW" /> 1813 <data android:scheme="geo" /> 1814 <category android:name="android.intent.category.DEFAULT" /> 1815 </intent-filter> 1816 </activity> 1817 </pre> 1818 1819 1820 1821 1822 1823 1824 1825 1826 <h2 id="Music">Music or Video</h2> 1827 1828 1829 <h3 id="PlayMedia">Play a media file</h3> 1830 1831 <p>To play a music file, use the {@link android.content.Intent#ACTION_VIEW} action and 1832 specify the URI location of the file in the intent data.</p> 1833 1834 <dl> 1835 <dt><b>Action</b></dt> 1836 <dd>{@link android.content.Intent#ACTION_VIEW}</dd> 1837 1838 <dt><b>Data URI Scheme</b></dt> 1839 <dd> 1840 <dl> 1841 <dt>{@code file:<em><URI></em>} 1842 <dt>{@code content:<em><URI></em>} 1843 <dt>{@code http:<em><URL></em>} 1844 </dl> 1845 </dd> 1846 1847 <dt><b>MIME Type</b></dt> 1848 <dd> 1849 <dl> 1850 <dt><code>"audio/*"</code> 1851 <dt><code>"application/ogg"</code> 1852 <dt><code>"application/x-ogg"</code> 1853 <dt><code>"application/itunes"</code> 1854 <dt>Or any other that your app may require. 1855 </dl> 1856 </dd> 1857 1858 </dl> 1859 1860 <p><b>Example intent:</b></p> 1861 <pre> 1862 public void playMedia(Uri file) { 1863 Intent intent = new Intent(Intent.ACTION_VIEW); 1864 intent.setData(file); 1865 if (intent.resolveActivity(getPackageManager()) != null) { 1866 startActivity(intent); 1867 } 1868 } 1869 </pre> 1870 1871 1872 <p><b>Example intent filter:</b></p> 1873 <pre> 1874 <activity ...> 1875 <intent-filter> 1876 <action android:name="android.intent.action.VIEW" /> 1877 <data android:type="audio/*" /> 1878 <data android:type="application/ogg" /> 1879 <category android:name="android.intent.category.DEFAULT" /> 1880 </intent-filter> 1881 </activity> 1882 </pre> 1883 1884 1885 <h3 id="PlaySearch">Play music based on a search query</h3> 1886 1887 <!-- Google Now box --> 1888 <div class="now-box"> 1889 <div class="now-img-cont"> 1890 <a href="#Now"> 1891 <img src="{@docRoot}guide/components/images/voice-icon.png" class="now-img" width="30" height="30" alt=""/> 1892 </a> 1893 </div> 1894 <p class="now-title">Google Now</p> 1895 <ul> 1896 <li>"play michael jackson billie jean"</li> 1897 </ul> 1898 </div> 1899 1900 <p>To play music based on a search query, use the 1901 {@link android.provider.MediaStore#INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH} intent. An app may fire 1902 this intent in response to the user's voice command to play music. The receiving app for this 1903 intent performs a search within its inventory to match existing content to the given query and 1904 starts playing that content.</p> 1905 1906 <p>This intent should include the {@link android.provider.MediaStore#EXTRA_MEDIA_FOCUS} string 1907 extra, which specifies the inteded search mode. For example, the search mode can specify whether 1908 the search is for an artist name or song name.</p> 1909 1910 <dl> 1911 <dt><b>Action</b></dt> 1912 <dd>{@link android.provider.MediaStore#INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH}</dd> 1913 1914 <dt><b>Data URI Scheme</b></dt> 1915 <dd>None</dd> 1916 1917 <dt><b>MIME Type</b></dt> 1918 <dd>None</dd> 1919 1920 <dt><b>Extras</b></dt> 1921 <dd> 1922 <dl> 1923 <dt>{@link android.provider.MediaStore#EXTRA_MEDIA_FOCUS MediaStore.EXTRA_MEDIA_FOCUS} (required)</dt> 1924 <dd> 1925 <p>Indicates the search mode (whether the user is looking for a particular artist, album, song, 1926 or playlist). Most search modes take additional extras. For example, if the user 1927 is interested in listening to a particular song, the intent might have three additional extras: 1928 the song title, the artist, and the album. This intent supports the following search modes for 1929 each value of {@link android.provider.MediaStore#EXTRA_MEDIA_FOCUS}:</p> 1930 <dl> 1931 <dt><p><em>Any</em> - <code>"vnd.android.cursor.item/*"</p></code></dt> 1932 <dd> 1933 <p>Play any music. The receiving app should play some music based on a smart choice, such 1934 as the last playlist the user listened to.</p> 1935 <p>Additional extras:</p> 1936 <ul> 1937 <li>{@link android.app.SearchManager#QUERY} (required) - An empty string. This extra is always 1938 provided for backward compatibility: existing apps that do not know about search modes can 1939 process this intent as an unstructured search.</li> 1940 </ul> 1941 </dd> 1942 <dt><p><em>Unstructured</em> - <code>"vnd.android.cursor.item/*"</code></p></dt> 1943 <dd> 1944 <p>Play a particular song, album or genre from an unstructured search query. Apps may generate 1945 an intent with this search mode when they can't identify the type of content the user wants to 1946 listen to. Apps should use more specific search modes when possible.</p> 1947 <p>Additional extras:</p> 1948 <ul> 1949 <li>{@link android.app.SearchManager#QUERY} (required) - A string that contains any combination 1950 of: the artist, the album, the song name, or the genre.</li> 1951 </ul> 1952 </dd> 1953 <dt><p><em>Genre</em> - 1954 {@link android.provider.MediaStore.Audio.Genres#ENTRY_CONTENT_TYPE Audio.Genres.ENTRY_CONTENT_TYPE}</p></dt> 1955 <dd> 1956 <p>Play music of a particular genre.</p> 1957 <p>Additional extras:</p> 1958 <ul> 1959 <li><code>"android.intent.extra.genre"</code> (required) - The genre.</li> 1960 <li>{@link android.app.SearchManager#QUERY} (required) - The genre. This extra is always provided 1961 for backward compatibility: existing apps that do not know about search modes can process 1962 this intent as an unstructured search.</li> 1963 </ul> 1964 </dd> 1965 <dt><p><em>Artist</em> - 1966 {@link android.provider.MediaStore.Audio.Artists#ENTRY_CONTENT_TYPE Audio.Artists.ENTRY_CONTENT_TYPE}</p></dt> 1967 <dd> 1968 <p>Play music from a particular artist.</p> 1969 <p>Additional extras:</p> 1970 <ul> 1971 <li>{@link android.provider.MediaStore#EXTRA_MEDIA_ARTIST} (required) - The artist.</li> 1972 <li><code>"android.intent.extra.genre"</code> - The genre.</li> 1973 <li>{@link android.app.SearchManager#QUERY} (required) - A string that contains any combination of 1974 the artist or the genre. This extra is always provided for backward compatibility: 1975 existing apps that do not know about search modes can process this intent as an unstructured 1976 search.</li> 1977 </ul> 1978 </dd> 1979 <dt><p><em>Album</em> - 1980 {@link android.provider.MediaStore.Audio.Albums#ENTRY_CONTENT_TYPE Audio.Albums.ENTRY_CONTENT_TYPE}</p></dt> 1981 <dd> 1982 <p>Play music from a particular album.</p> 1983 <p>Additional extras:</p> 1984 <ul> 1985 <li>{@link android.provider.MediaStore#EXTRA_MEDIA_ALBUM} (required) - The album.</li> 1986 <li>{@link android.provider.MediaStore#EXTRA_MEDIA_ARTIST} - The artist.</li> 1987 <li><code>"android.intent.extra.genre"</code> - The genre.</li> 1988 <li>{@link android.app.SearchManager#QUERY} (required) - A string that contains any combination of 1989 the album or the artist. This extra is always provided for backward 1990 compatibility: existing apps that do not know about search modes can process this intent as an 1991 unstructured search.</li> 1992 </ul> 1993 </dd> 1994 <dt><p><em>Song</em> - <code>"vnd.android.cursor.item/audio"</code></p></dt> 1995 <dd> 1996 <p>Play a particular song.</p> 1997 <p>Additional extras:</p> 1998 <ul> 1999 <li>{@link android.provider.MediaStore#EXTRA_MEDIA_ALBUM} - The album.</li> 2000 <li>{@link android.provider.MediaStore#EXTRA_MEDIA_ARTIST} - The artist.</li> 2001 <li><code>"android.intent.extra.genre"</code> - The genre.</li> 2002 <li>{@link android.provider.MediaStore#EXTRA_MEDIA_TITLE} (required) - The song name.</li> 2003 <li>{@link android.app.SearchManager#QUERY} (required) - A string that contains any combination of: 2004 the album, the artist, the genre, or the title. This extra is always provided for 2005 backward compatibility: existing apps that do not know about search modes can process this 2006 intent as an unstructured search.</li> 2007 </ul> 2008 </dd> 2009 <dt><p><em>Playlist</em> - {@link android.provider.MediaStore.Audio.Playlists#ENTRY_CONTENT_TYPE Audio.Playlists.ENTRY_CONTENT_TYPE}</p></dt> 2010 <dd> 2011 <p>Play a particular playlist or a playlist that matches some criteria specified 2012 by additional extras.</p> 2013 <p>Additional extras:</p> 2014 <ul> 2015 <li>{@link android.provider.MediaStore#EXTRA_MEDIA_ALBUM} - The album.</li> 2016 <li>{@link android.provider.MediaStore#EXTRA_MEDIA_ARTIST} - The artist.</li> 2017 <li><code>"android.intent.extra.genre"</code> - The genre.</li> 2018 <li><code>"android.intent.extra.playlist"</code> - The playlist.</li> 2019 <li>{@link android.provider.MediaStore#EXTRA_MEDIA_TITLE} - The song name that the playlist is 2020 based on.</li> 2021 <li>{@link android.app.SearchManager#QUERY} (required) - A string that contains any combination 2022 of: the album, the artist, the genre, the playlist, or the title. This extra is always 2023 provided for backward compatibility: existing apps that do not know about search modes can 2024 process this intent as an unstructured search.</li> 2025 </ul> 2026 </dd> 2027 </dl> 2028 </dd> 2029 </dl> 2030 </dd> 2031 </dl> 2032 2033 2034 2035 <p><b>Example intent:</b></p> 2036 <p>If the user wants to listen to music from a particular artist, a search app may generate the 2037 following intent:</p> 2038 <pre> 2039 public void playSearchArtist(String artist) { 2040 Intent intent = new Intent(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH); 2041 intent.putExtra(MediaStore.EXTRA_MEDIA_FOCUS, 2042 MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE); 2043 intent.putExtra(MediaStore.EXTRA_MEDIA_ARTIST, artist); 2044 intent.putExtra(SearchManager.QUERY, artist); 2045 if (intent.resolveActivity(getPackageManager()) != null) { 2046 startActivity(intent); 2047 } 2048 } 2049 </pre> 2050 2051 <p><b>Example intent filter:</b></p> 2052 <pre> 2053 <activity ...> 2054 <intent-filter> 2055 <action android:name="android.media.action.MEDIA_PLAY_FROM_SEARCH" /> 2056 <category android:name="android.intent.category.DEFAULT" /> 2057 </intent-filter> 2058 </activity> 2059 </pre> 2060 <p>When handling this intent, your activity should check the value of the 2061 {@link android.provider.MediaStore#EXTRA_MEDIA_FOCUS} extra in the incoming 2062 {@link android.content.Intent} to determine the search mode. Once your activity has identified 2063 the search mode, it should read the values of the additional extras for that particular search mode. 2064 With this information your app can then perform the search within its inventory to play the 2065 content that matches the search query. For example:</p> 2066 <pre> 2067 protected void onCreate(Bundle savedInstanceState) { 2068 ... 2069 Intent intent = this.getIntent(); 2070 if (intent.getAction().compareTo(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH) == 0) { 2071 2072 String mediaFocus = intent.getStringExtra(MediaStore.EXTRA_MEDIA_FOCUS); 2073 String query = intent.getStringExtra(SearchManager.QUERY); 2074 2075 // Some of these extras may not be available depending on the search mode 2076 String album = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ALBUM); 2077 String artist = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ARTIST); 2078 String genre = intent.getStringExtra("android.intent.extra.genre"); 2079 String playlist = intent.getStringExtra("android.intent.extra.playlist"); 2080 String title = intent.getStringExtra(MediaStore.EXTRA_MEDIA_TITLE); 2081 2082 // Determine the search mode and use the corresponding extras 2083 if (mediaFocus == null) { 2084 // 'Unstructured' search mode (backward compatible) 2085 playUnstructuredSearch(query); 2086 2087 } else if (mediaFocus.compareTo("vnd.android.cursor.item/*") == 0) { 2088 if (query.isEmpty()) { 2089 // 'Any' search mode 2090 playResumeLastPlaylist(); 2091 } else { 2092 // 'Unstructured' search mode 2093 playUnstructuredSearch(query); 2094 } 2095 2096 } else if (mediaFocus.compareTo(MediaStore.Audio.Genres.ENTRY_CONTENT_TYPE) == 0) { 2097 // 'Genre' search mode 2098 playGenre(genre); 2099 2100 } else if (mediaFocus.compareTo(MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE) == 0) { 2101 // 'Artist' search mode 2102 playArtist(artist, genre); 2103 2104 } else if (mediaFocus.compareTo(MediaStore.Audio.Albums.ENTRY_CONTENT_TYPE) == 0) { 2105 // 'Album' search mode 2106 playAlbum(album, artist); 2107 2108 } else if (mediaFocus.compareTo("vnd.android.cursor.item/audio") == 0) { 2109 // 'Song' search mode 2110 playSong(album, artist, genre, title); 2111 2112 } else if (mediaFocus.compareTo(MediaStore.Audio.Playlists.ENTRY_CONTENT_TYPE) == 0) { 2113 // 'Playlist' search mode 2114 playPlaylist(album, artist, genre, playlist, title); 2115 } 2116 } 2117 } 2118 </pre> 2119 2120 2121 2122 2123 <h2 id="Phone">Phone</h2> 2124 2125 2126 <h3 id="DialPhone">Initiate a phone call</h3> 2127 2128 <p>To open the phone app and dial a phone number, use the {@link 2129 android.content.Intent#ACTION_DIAL} action and specify a phone number using 2130 the URI scheme defined below. When the phone app opens, it displays the phone number 2131 but the user must press the <em>Call</em> button to begin the phone call.</p> 2132 2133 <!-- Google Now box --> 2134 <div class="now-box"> 2135 <div class="now-img-cont"> 2136 <a href="#Now"> 2137 <img src="{@docRoot}guide/components/images/voice-icon.png" class="now-img" width="30" height="30" alt=""/> 2138 </a> 2139 </div> 2140 <p class="now-title">Google Now</p> 2141 <ul> 2142 <li>"call 555-5555"</li> 2143 <li>"call bob"</li> 2144 <li>"call voicemail"</li> 2145 </ul> 2146 </div> 2147 2148 <p>To place a phone call directly, use the {@link android.content.Intent#ACTION_CALL} action 2149 and specify a phone number using the URI scheme defined below. When the phone app opens, it 2150 begins the phone call; the user does not need to press the <em>Call</em> button.</p> 2151 2152 <p>The {@link android.content.Intent#ACTION_CALL} action requires that you add the 2153 <code>CALL_PHONE</code> permission to your manifest file:</p> 2154 2155 <pre style="margin-top:45px"> 2156 <uses-permission android:name="android.permission.CALL_PHONE" /> 2157 </pre> 2158 2159 <dl> 2160 <dt><b>Action</b></dt> 2161 <dd> 2162 <ul> 2163 <li>{@link android.content.Intent#ACTION_DIAL} - Opens the dialer or phone app.</li> 2164 <li>{@link android.content.Intent#ACTION_CALL} - Places a phone call (requires the 2165 <code>CALL_PHONE</code> permission)</li> 2166 </ul> 2167 </dd> 2168 2169 <dt><b>Data URI Scheme</b></dt> 2170 <dd> 2171 <ul> 2172 <li>{@code tel:<phone-number>}</li> 2173 <li>{@code voicemail:<phone-number>}</li> 2174 </ul> 2175 </dd> 2176 2177 <dt><b>MIME Type</b></dt> 2178 <dd>None</dd> 2179 2180 </dl> 2181 2182 2183 <p>Valid telephone numbers are those defined 2184 in <a href="http://tools.ietf.org/html/rfc3966">the IETF RFC 3966</a>. 2185 Valid examples include the following:</p> 2186 <ul> 2187 <li><code>tel:2125551212</code> </li> 2188 <li><code>tel:(212) 555 1212</code></li> 2189 </ul> 2190 <p>The Phone's dialer is good at normalizing schemes, such as 2191 telephone numbers. So the scheme described isn't strictly required in the 2192 {@link android.net.Uri#parse(String) Uri.parse()} method. 2193 However, if you have not tried a scheme or are unsure whether it 2194 can be handled, use the {@link android.net.Uri#fromParts Uri.fromParts()} 2195 method instead.</p> 2196 2197 2198 <p><b>Example intent:</b></p> 2199 <pre> 2200 public void dialPhoneNumber(String phoneNumber) { 2201 Intent intent = new Intent(Intent.ACTION_DIAL); 2202 intent.setData(Uri.parse("tel:" + phoneNumber)); 2203 if (intent.resolveActivity(getPackageManager()) != null) { 2204 startActivity(intent); 2205 } 2206 } 2207 </pre> 2208 2209 2210 2211 2212 2213 2214 2215 <h2 id="Settings">Settings</h2> 2216 2217 <h3 id="OpenSettings">Open a specific section of Settings</h3> 2218 2219 <p>To open a screen in the system settings when your app requires the user to change something, 2220 use one of the following intent actions to open the settings screen respective to the action name. 2221 </p> 2222 2223 <dl> 2224 <dt><b>Action</b></dt> 2225 <dd> 2226 {@link android.provider.Settings#ACTION_SETTINGS}<br/> 2227 {@link android.provider.Settings#ACTION_WIRELESS_SETTINGS}<br/> 2228 {@link android.provider.Settings#ACTION_AIRPLANE_MODE_SETTINGS}<br/> 2229 {@link android.provider.Settings#ACTION_WIFI_SETTINGS}<br/> 2230 {@link android.provider.Settings#ACTION_APN_SETTINGS}<br/> 2231 {@link android.provider.Settings#ACTION_BLUETOOTH_SETTINGS}<br/> 2232 {@link android.provider.Settings#ACTION_DATE_SETTINGS}<br/> 2233 {@link android.provider.Settings#ACTION_LOCALE_SETTINGS}<br/> 2234 {@link android.provider.Settings#ACTION_INPUT_METHOD_SETTINGS}<br/> 2235 {@link android.provider.Settings#ACTION_DISPLAY_SETTINGS}<br/> 2236 {@link android.provider.Settings#ACTION_SECURITY_SETTINGS}<br/> 2237 {@link android.provider.Settings#ACTION_LOCATION_SOURCE_SETTINGS}<br/> 2238 {@link android.provider.Settings#ACTION_INTERNAL_STORAGE_SETTINGS}<br/> 2239 {@link android.provider.Settings#ACTION_MEMORY_CARD_SETTINGS}<br/> 2240 <p>See the {@link android.provider.Settings} documentation for additional settings screens 2241 that are available.</p> 2242 </dd> 2243 2244 <dt><b>Data URI Scheme</b></dt> 2245 <dd>None</dd> 2246 2247 <dt><b>MIME Type</b></dt> 2248 <dd>None</dd> 2249 2250 </dl> 2251 2252 <p><b>Example intent:</b></p> 2253 <pre> 2254 public void openWifiSettings() { 2255 Intent intent = new Intent(Intent.ACTION_WIFI_SETTINGS); 2256 if (intent.resolveActivity(getPackageManager()) != null) { 2257 startActivity(intent); 2258 } 2259 } 2260 </pre> 2261 2262 2263 2264 2265 2266 2267 2268 <h2 id="Messaging">Text Messaging</h2> 2269 2270 <h3 id="SendMessage">Compose an SMS/MMS message with attachment</h3> 2271 2272 <p>To initiate an SMS or MMS text message, use one of the intent actions below and specify message 2273 details such as the phone number, subject, and message body using the extra keys listed below.</p> 2274 2275 <dl> 2276 <dt><b>Action</b></dt> 2277 <dd>{@link android.content.Intent#ACTION_SENDTO} or<br> 2278 {@link android.content.Intent#ACTION_SEND} or<br> 2279 {@link android.content.Intent#ACTION_SEND_MULTIPLE}</dd> 2280 2281 <dt><b>Data URI Scheme</b></dt> 2282 <dd> 2283 <dl> 2284 <dt>{@code sms:<em><phone_number></em>} 2285 <dt>{@code smsto:<em><phone_number></em>} 2286 <dt>{@code mms:<em><phone_number></em>} 2287 <dt>{@code mmsto:<em><phone_number></em>} 2288 </dl> 2289 <p>Each of these schemes are handled the same. 2290 </dd> 2291 2292 <dt><b>MIME Type</b></dt> 2293 <dd> 2294 <dl> 2295 <dt>{@link org.apache.http.protocol.HTTP#PLAIN_TEXT_TYPE} (<code>"text/plain"</code>) 2296 <dt><code>"image/*"</code> 2297 <dt><code>"video/*"</code> 2298 </dl> 2299 </dd> 2300 2301 <dt><b>Extras</b></dt> 2302 <dd> 2303 <dl> 2304 <dt><code>"subject"</code></dt> 2305 <dd>A string for the message subject (usually for MMS only).</dd> 2306 <dt><code>"sms_body"</code></dt> 2307 <dd>A string for the text message.</dd> 2308 <dt>{@link android.content.Intent#EXTRA_STREAM}</dt> 2309 <dd>A {@link android.net.Uri} pointing to the 2310 image or video to attach. If using the {@link android.content.Intent#ACTION_SEND_MULTIPLE} action, 2311 this extra should be an {@link java.util.ArrayList} of {@link 2312 android.net.Uri}s pointing to the images/videos to attach.</dd> 2313 <dl> 2314 </dd> 2315 2316 </dl> 2317 2318 <p><b>Example intent:</b></p> 2319 <pre> 2320 public void composeMmsMessage(String message, Uri attachment) { 2321 Intent intent = new Intent(Intent.ACTION_SENDTO); 2322 intent.setType(HTTP.PLAIN_TEXT_TYPE); 2323 intent.putExtra("sms_body", message); 2324 intent.putExtra(Intent.EXTRA_STREAM, attachment); 2325 if (intent.resolveActivity(getPackageManager()) != null) { 2326 startActivity(intent); 2327 } 2328 } 2329 </pre> 2330 2331 <p>If you want to ensure that your intent is handled only by a text messaging app (and not other 2332 email or social apps), then use the {@link android.content.Intent#ACTION_SENDTO} action 2333 and include the {@code "smsto:"} data scheme. For example:</p> 2334 2335 <pre> 2336 public void composeMmsMessage(String message, Uri attachment) { 2337 Intent intent = new Intent(Intent.ACTION_SEND); 2338 intent.setData(Uri.parse("smsto:")); // This ensures only SMS apps respond 2339 intent.putExtra("sms_body", message); 2340 intent.putExtra(Intent.EXTRA_STREAM, attachment); 2341 if (intent.resolveActivity(getPackageManager()) != null) { 2342 startActivity(intent); 2343 } 2344 } 2345 </pre> 2346 2347 2348 <p><b>Example intent filter:</b></p> 2349 <pre> 2350 <activity ...> 2351 <intent-filter> 2352 <action android:name="android.intent.action.SEND" /> 2353 <data android:type="text/plain" /> 2354 <data android:type="image/*" /> 2355 <category android:name="android.intent.category.DEFAULT" /> 2356 </intent-filter> 2357 </activity> 2358 </pre> 2359 2360 <p class="note"><strong>Note:</strong> If you're developing an SMS/MMS messaging app, you must 2361 implement intent filters for several additional actions in order to be available as the 2362 <em>default SMS app</em> on Android 4.4 and higher. For more information, see the documentation 2363 at {@link android.provider.Telephony}.</p> 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 <h2 id="Browser">Web Browser</h2> 2375 2376 <h3 id="ViewUrl">Load a web URL</h3> 2377 2378 <!-- Google Now box --> 2379 <div class="now-box"> 2380 <div class="now-img-cont"> 2381 <a href="#Now"> 2382 <img src="{@docRoot}guide/components/images/voice-icon.png" class="now-img" width="30" height="30" alt=""/> 2383 </a> 2384 </div> 2385 <p class="now-title">Google Now</p> 2386 <ul> 2387 <li>"open example.com"</li> 2388 </ul> 2389 </div> 2390 2391 <p>To open a web page, use the {@link android.content.Intent#ACTION_VIEW} action 2392 and specify the web URL in the intent data.</p> 2393 2394 <dl> 2395 <dt><b>Action</b></dt> 2396 <dd>{@link android.content.Intent#ACTION_VIEW}<dd> 2397 2398 <dt><b>Data URI Scheme</b></dt> 2399 <dd>{@code http:<em><URL></em>}<br/> 2400 {@code https:<em><URL></em>}</dd> 2401 2402 <dt><b>MIME Type</b></dt> 2403 <dd> 2404 <dl> 2405 <dt>{@link org.apache.http.protocol.HTTP#PLAIN_TEXT_TYPE} (<code>"text/plain"</code>) 2406 <dt><code>"text/html"</code> 2407 <dt><code>"application/xhtml+xml"</code> 2408 <dt><code>"application/vnd.wap.xhtml+xml"</code> 2409 </dl> 2410 </dd> 2411 </dl> 2412 2413 2414 <p><b>Example intent:</b></p> 2415 <pre> 2416 public void openWebPage(String url) { 2417 Uri webpage = Uri.parse(url); 2418 Intent intent = new Intent(Intent.ACTION_VIEW, webpage); 2419 if (intent.resolveActivity(getPackageManager()) != null) { 2420 startActivity(intent); 2421 } 2422 } 2423 </pre> 2424 2425 2426 <p><b>Example intent filter:</b></p> 2427 <pre> 2428 <activity ...> 2429 <intent-filter> 2430 <action android:name="android.intent.action.VIEW" /> 2431 <!-- Include the host attribute if you want your app to respond 2432 only to URLs with your app's domain. --> 2433 <data android:scheme="http" android:host="www.example.com" /> 2434 <category android:name="android.intent.category.DEFAULT" /> 2435 <!-- The BROWSABLE category is required to get links from web pages. --> 2436 <category android:name="android.intent.category.BROWSABLE" /> 2437 </intent-filter> 2438 </activity> 2439 </pre> 2440 2441 2442 <p class="note"><strong>Tip:</strong> If your Android app provides functionality similar to 2443 your web site, include an intent filter for URLs that point to your web site. Then, 2444 if users have your app installed, links from emails or other web pages pointing to your web site 2445 open your Android app instead of your web page.</p> 2446 2447 2448 2449 2450 <h3 id="SearchWeb">Perform a web search</h3> 2451 2452 <p>To initiate a web search, use the {@link android.content.Intent#ACTION_WEB_SEARCH} action 2453 and specify the search string in the 2454 {@link android.app.SearchManager#QUERY SearchManager.QUERY} extra.</p> 2455 2456 2457 <dl> 2458 <dt><b>Action</b></dt> 2459 <dd>{@link android.content.Intent#ACTION_WEB_SEARCH}</dd> 2460 2461 <dt><b>Data URI Scheme</b></dt> 2462 <dd>None</dd> 2463 2464 <dt><b>MIME Type</b></dt> 2465 <dd>None</dd> 2466 2467 <dt><b>Extras</b></dt> 2468 <dd> 2469 <dl> 2470 <dt>{@link android.app.SearchManager#QUERY SearchManager.QUERY}</dt> 2471 <dd>The search string.</dd> 2472 </dl> 2473 </dd> 2474 </dl> 2475 2476 <p><b>Example intent:</b></p> 2477 <pre> 2478 public void searchWeb(String query) { 2479 Intent intent = new Intent(Intent.ACTION_SEARCH); 2480 intent.putExtra(SearchManager.QUERY, query); 2481 if (intent.resolveActivity(getPackageManager()) != null) { 2482 startActivity(intent); 2483 } 2484 } 2485 </pre> 2486 2487 2488 2489 2490 2491 2492 2493 <h2 id="AdbIntents">Verify Intents with the Android Debug Bridge</h2> 2494 2495 <p>To verify that your app responds to the intents that you want to support, you can use the 2496 <a href="{@docRoot}tools/help/adb.html"><code>adb</code></a> tool to fire specific intents:</p> 2497 2498 <ol> 2499 <li>Set up an Android device for <a href="{@docRoot}tools/device.html#setting-up">development</a>, 2500 or use a <a href="{@docRoot}tools/devices/emulator.html#avds">virtual device</a>.</li> 2501 <li>Install a version of your app that handles the intents you want to support.</li> 2502 <li>Fire an intent using <code>adb</code>: 2503 <pre class="no-pretty-print"> 2504 adb shell am start -a <ACTION> -t <MIME_TYPE> -d <DATA> \ 2505 -e <EXTRA_NAME> <EXTRA_VALUE> -n <ACTIVITY> 2506 </pre> 2507 <p>For example:</p> 2508 <pre class="no-pretty-print"> 2509 adb shell am start -a android.intent.action.DIAL \ 2510 -d tel:555-5555 -n org.example.MyApp/.MyActivity 2511 </pre> 2512 <li>If you defined the required intent filters, your app should handle the intent.</li> 2513 </ol> 2514 2515 2516 <p>For more information, see 2517 <a href="{@docRoot}tools/help/adb.html#am">Using activity manager (am)</a>.</p> 2518 2519 2520 2521 2522 2523 2524 <h2 id="Now">Intents Fired by Google Now</h2> 2525 2526 <p><a href="http://www.google.com/landing/now/">Google Now</a> recognizes many voice commands 2527 and fires intents for them. As such, users may launch your app with a Google Now voice command 2528 if your app declares the corresponding intent filter. For example, if your app can 2529 <a href="#CreateAlarm">set an alarm</a> and you add the corresponding intent filter to your 2530 manifest file, Google Now lets users choose your app when they request to set an alarm, as 2531 shown in figure 1.</p> 2532 2533 <img src="{@docRoot}guide/components/images/google-action.png" 2534 srcset="{@docRoot}guide/components/images/google-action_2x.png 2x" 2535 width="700" height="241" alt=""/> 2536 <p class="img-caption"><strong>Figure 1.</strong> Google Now lets users choose from installed 2537 apps that support a given action.</p> 2538 2539 <p>Google Now recognizes voice commands for the actions listed in table 1. For more information 2540 about declaring each intent filter, click on the action description.</p> 2541 2542 <p class="table-caption"><strong>Table 1.</strong> Voice commands recognized by Google Now 2543 (Google Search app v3.6).</p> 2544 <table> 2545 <tr> 2546 <th>Category</th> 2547 <th>Details and Examples</th> 2548 <th>Action Name</th> 2549 </tr> 2550 <tr> 2551 <td rowspan="2" style="vertical-align:middle">Alarm</td> 2552 <td> 2553 <p><a href="#CreateAlarm">Set alarm</a></p> 2554 <ul class="now-list"> 2555 <li>"set an alarm for 7 am"</li> 2556 </ul> 2557 </td> 2558 <td>{@link android.provider.AlarmClock#ACTION_SET_ALARM AlarmClock.ACTION_SET_ALARM}</td> 2559 </tr> 2560 <tr> 2561 <td> 2562 <p><a href="#CreateTimer">Set timer</a></p> 2563 <ul class="now-list"> 2564 <li>"set a timer for 5 minutes"</li> 2565 </ul> 2566 </td> 2567 <td>{@link android.provider.AlarmClock#ACTION_SET_TIMER AlarmClock.ACTION_SET_TIMER}</td> 2568 </tr> 2569 <tr> 2570 <td style="vertical-align:middle">Communication</td> 2571 <td> 2572 <p><a href="#DialPhone">Call a number</a></p> 2573 <ul class="now-list"> 2574 <li>"call 555-5555"</li> 2575 <li>"call bob"</li> 2576 <li>"call voicemail"</li> 2577 </ul> 2578 </td> 2579 <td>{@link android.content.Intent#ACTION_CALL Intent.ACTION_CALL}</td> 2580 </tr> 2581 <tr> 2582 <td rowspan="5" style="vertical-align:middle">Fitness</td> 2583 <td> 2584 <p><a href="#TrackRide">Start/stop a bike ride</a></p> 2585 <ul class="now-list"> 2586 <li>"start cycling"</li> 2587 <li>"start my bike ride"</li> 2588 <li>"stop cycling"</li> 2589 </ul> 2590 </td> 2591 <td><code>"vnd.google.fitness.TRACK"</code></td> 2592 </tr> 2593 <tr> 2594 <td> 2595 <p><a href="#TrackRun">Start/stop a run</a></p> 2596 <ul class="now-list"> 2597 <li>"track my run"</li> 2598 <li>"start running"</li> 2599 <li>"stop running"</li> 2600 </ul> 2601 </td> 2602 <td><code>"vnd.google.fitness.TRACK"</code></td> 2603 </tr> 2604 <tr> 2605 <td> 2606 <p><a href="#TrackWorkout">Start/stop a workout</a></p> 2607 <ul class="now-list"> 2608 <li>"start a workout"</li> 2609 <li>"track my workout"</li> 2610 <li>"stop workout"</li> 2611 </ul> 2612 </td> 2613 <td><code>"vnd.google.fitness.TRACK"</code></td> 2614 </tr> 2615 <tr> 2616 <td> 2617 <p><a href="#ShowHeartRate">Show heart rate</a></p> 2618 <ul class="now-list"> 2619 <li>"what's my heart rate"</li> 2620 <li>"what's my bpm"</li> 2621 </ul> 2622 </td> 2623 <td><code>"vnd.google.fitness.VIEW"</code></td> 2624 </tr> 2625 <tr> 2626 <td> 2627 <p><a href="#ShowStepCount">Show step count</a></p> 2628 <ul class="now-list"> 2629 <li>"how many steps have I taken"</li> 2630 <li>"what's my step count"</li> 2631 </ul> 2632 </td> 2633 <td><code>"vnd.google.fitness.VIEW"</code></td> 2634 </tr> 2635 <tr> 2636 <td style="vertical-align:middle">Local</td> 2637 <td> 2638 <p><a href="#CallCar">Book a car</a></p> 2639 <ul class="now-list"> 2640 <li>"call me a car"</li> 2641 <li>"book me a taxi"</li> 2642 </ul> 2643 </td> 2644 <td><a href="{@docRoot}reference/com/google/android/gms/actions/ReserveIntents.html#ACTION_RESERVE_TAXI_RESERVATION"> 2645 <code>ReserveIntents<br/>.ACTION_RESERVE_TAXI_RESERVATION</code></a></td> 2646 </tr> 2647 <tr> 2648 <td rowspan="3" style="vertical-align:middle">Media</td> 2649 <td> 2650 <p><a href="#PlaySearch">Play music from search</a></p> 2651 <ul class="now-list"> 2652 <li>"play michael jackson billie jean"</li> 2653 </ul> 2654 </td> 2655 <td>{@link android.provider.MediaStore#INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH MediaStore<br/>.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH}</td> 2656 </tr> 2657 <tr> 2658 <td> 2659 <p><a href="#CameraStill">Take a picture</a></p> 2660 <ul class="now-list"> 2661 <li>"take a picture"</li> 2662 </ul> 2663 </td> 2664 <td>{@link android.provider.MediaStore#INTENT_ACTION_STILL_IMAGE_CAMERA MediaStore<br/>.INTENT_ACTION_STILL_IMAGE_CAMERA}</td> 2665 </tr> 2666 <tr> 2667 <td> 2668 <p><a href="#CameraVideo">Record a video</a></p> 2669 <ul class="now-list"> 2670 <li>"record a video"</li> 2671 </ul> 2672 </td> 2673 <td>{@link android.provider.MediaStore#INTENT_ACTION_VIDEO_CAMERA MediaStore<br/>.INTENT_ACTION_VIDEO_CAMERA}</td> 2674 </tr> 2675 <tr> 2676 <td style="vertical-align:middle">Web browser</td> 2677 <td> 2678 <p><a href="#ViewUrl">Open URL</a></p> 2679 <ul class="now-list"> 2680 <li>"open example.com"</li> 2681 </ul> 2682 </td> 2683 <td>{@link android.content.Intent#ACTION_VIEW Intent.ACTION_VIEW}</td> 2684 </tr> 2685 </table> 2686
