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