diff options
Diffstat (limited to 'docs/html/guide/components/intents-common.jd')
| -rw-r--r-- | docs/html/guide/components/intents-common.jd | 1312 |
1 files changed, 1312 insertions, 0 deletions
diff --git a/docs/html/guide/components/intents-common.jd b/docs/html/guide/components/intents-common.jd new file mode 100644 index 0000000..f09ef9f --- /dev/null +++ b/docs/html/guide/components/intents-common.jd @@ -0,0 +1,1312 @@ +page.title=Common Intents +page.tags="IntentFilter" +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>In this document + <a href="#" onclick="hideNestedItems('#tocIntents',this);return false;" class="header-toggle"> + <span class="more">show more</span> + <span class="less" style="display:none">show less</span></a></h2> + +<ol id="tocIntents" class="hide-nested"> + <li><a href="#Camera">Camera</a> + <ol> + <li><a href="#ImageCapture">Capture a picture or video and return it</a></li> + </ol> + </li> + <li><a href="#Contacts">Contacts/People App</a> + <ol> + <li><a href="#PickContact">Select a contact</a></li> + <li><a href="#PickContactDat">Select specific contact data</a></li> + <li><a href="#ViewContact">View a contact</a></li> + <li><a href="#EditContact">Edit an existing contact</a></li> + <li><a href="#InsertContact">Insert a contact</a></li> + </ol> + </li> + <li><a href="#Email">Email</a> + <ol> + <li><a href="#ComposeEmail">Compose an email with optional attachments</a></li> + </ol> + </li> + <li><a href="#Storage">File Storage</a> + <ol> + <li><a href="#GetFile">Retrieve a specific type of file</a></li> + <li><a href="#OpenFile">Open a specific type of file</a></li> + </ol> + </li> + <li><a href="#Maps">Maps</a> + <ol> + <li><a href="#ViewMap">Show a location on a map</a></li> + </ol> + </li> + <li><a href="#Music">Music or Video</a> + <ol> + <li><a href="#PlayMedia">Play a media file</a></li> + </ol> + </li> + <li><a href="#Phone">Phone</a> + <ol> + <li><a href="#DialPhone">Initiate a phone call</a></li> + </ol> + </li> + <li><a href="#Settings">Settings</a> + <ol> + <li><a href="#OpenSettings">Open a specific section of Settings</a></li> + </ol> + </li> + <li><a href="#Messaging">Text Messaging</a> + <ol> + <li><a href="#SendMessage">Compose an SMS/MMS message with attachment</a></li> + </ol> + </li> + <li><a href="#Browser">Web Browser</a> + <ol> + <li><a href="#ViewUrl">Load a web URL</a></li> + <li><a href="#SearchWeb">Perform a web search</a></li> + </ol> + </li> +</ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent +Filters</a></li> + </ol> +</div> +</div> + + +<p>An intent allows you to start an activity in another app by describing a simple +action you'd like to perform (such as "view a map" or "take a picture") +in an {@link android.content.Intent} object. This type of intent is +called an <em>implicit</em> intent because it does not specify the app component +to start, but instead specifies an <em>action</em> and provides some +<em>data</em> with which to perform the action.</p> + +<p>When you call +{@link android.content.Context#startActivity startActivity()} or +{@link android.app.Activity#startActivityForResult startActivityForResult()} and pass it an +implicit intent, the system <a href="{@docRoot}guide/components/intents-filters.html#Resolution" +>resolves the intent</a> to an app that can handle the intent +and starts its corresponding {@link android.app.Activity}. If there's more than one app +that can handle the intent, the system presents the user with a dialog to pick which app +to use.</p> + +<p>This page describes several implicit intents that you can use to perform common actions, +organized by the type of app that handles the intent. Each section also shows how you can +create an <a href="{@docRoot}guide/components/intents-filters.html#Receiving">intent filter</a> to +advertise your app's ability to perform the same action.</p> + +<p class="caution"><strong>Caution:</strong> If there are no apps on the device that can receive +the implicit intent, your app will crash when it calls {@link android.content.Context#startActivity +startActivity()}. To first verify that an app exists to receive the intent, call {@link +android.content.Intent#resolveActivity resolveActivity()} on your {@link android.content.Intent} +object. If the result is non-null, there is at least one app that can handle the intent and +it's safe to call {@link android.content.Context#startActivity startActivity()}. If the result is +null, you should not use the intent and, if possible, you should disable the feature that invokes +the intent.</p> + + +<p>If you're not familiar with how to create intents or intent filters, you should first read +<a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>.</p> + + + + + +<h2 id="Camera">Camera</h2> + + + +<h3 id="ImageCapture">Capture a picture or video and return it</h3> + +<p>To open a camera app and receive the resulting photo or video, use the {@link +android.provider.MediaStore#ACTION_IMAGE_CAPTURE} or {@link +android.provider.MediaStore#ACTION_VIDEO_CAPTURE} action. Also specify the URI location where you'd +like the camera to save the photo or video, in the {@link android.provider.MediaStore#EXTRA_OUTPUT} +extra.</p> + + +<dl> +<dt><b>Action</b></dt> +<dd>{@link android.provider.MediaStore#ACTION_IMAGE_CAPTURE} or<br> + {@link android.provider.MediaStore#ACTION_VIDEO_CAPTURE}</dd> + +<dt><b>Data URI Scheme</b></dt> +<dd>None</dd> + +<dt><b>MIME Type</b></dt> +<dd>None</dd> + +<dt><b>Extras</b></dt> +<dd> + <dl> + <dt>{@link android.provider.MediaStore#EXTRA_OUTPUT}</dt> + <dd>The URI location where the camera app should save the photo or + video file (as a {@link android.net.Uri} object).</dd> + </dl> +</dd> +</dl> + +<p>When the camera app successfully returns +focus to your activity (your app receives the {@link android.app.Activity#onActivityResult +onActivityResult()} callback), you can access the photo or video at the URI you specified +with the {@link android.provider.MediaStore#EXTRA_OUTPUT} value.</p> + +<p class="note"><strong>Note:</strong> When you use {@link +android.provider.MediaStore#ACTION_IMAGE_CAPTURE} to capture a photo, the camera may also return a +downscaled copy (a thumbnail) of the photo in the result {@link +android.content.Intent}, saved as a {@link android.graphics.Bitmap} in an extra field named +<code>"data"</code>.</p> + + +<p><b>Example intent:</b></p> +<pre> +static final int REQUEST_IMAGE_CAPTURE = 1; +static final Uri mLocationForPhotos; + +public void capturePhoto(String targetFilename) { + Intent intent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE); + intent.putExtra(MediaStore.EXTRA_OUTPUT, + Uri.withAppendedPath(mLocationForPhotos, targetFilename); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivityForResult(intent, REQUEST_IMAGE_CAPTURE); + } +} + +@Override +protected void onActivityResult(int requestCode, int resultCode, Intent data) { + if (requestCode == REQUEST_IMAGE_CAPTURE && resultCode == RESULT_OK) { + Bitmap thumbnail = data.getParcelable("data"); + // Do other work with full size photo saved in mLocationForPhotos + ... + } +} +</pre> + +<p>For more information about how to use this intent to capture a photo, including +how to create an appropriate {@link android.net.Uri} for the output location, read +<a href="{@docRoot}training/camera/photobasics.html">Taking Photos Simply</a> or +<a href="{@docRoot}training/camera/videobasics.html">Taking Videos Simply</a>.</p> + +<p><b>Example intent filter:</b></p> +<pre> +<activity ...> + <intent-filter> + <action android:name="android.media.action.IMAGE_CAPTURE" /> + <category android:name="android.intent.category.DEFAULT" /> + </intent-filter> +</activity> +</pre> + +<p>When handling this intent, your activity should check for the {@link +android.provider.MediaStore#EXTRA_OUTPUT} extra in the incoming {@link android.content.Intent}, +then save the captured image or video at the location specified by that extra and call {@link +android.app.Activity#setResult(int,Intent) setResult()} with an +{@link android.content.Intent} that includes a compressed thumbnail +in an extra named <code>"data"</code>.</p> + + + + +<h2 id="Contacts">Contacts/People App</h2> + + +<h3 id="PickContact">Select a contact</h3> + +<p>To have the user select a contact and provide your app access to all the contact information, +use the {@link android.content.Intent#ACTION_PICK} action and specify the MIME type to +{@link android.provider.ContactsContract.Contacts#CONTENT_TYPE +Contacts.CONTENT_TYPE}.</p> + +<p>The result {@link android.content.Intent} delivered to your {@link +android.app.Activity#onActivityResult onActivityResult()} callback contains the +<code>content:</code> URI pointing to the selected contact. The response grants +your app temporary permissions to read that contact using the <a +href="{@docRoot}guide/topics/providers/contacts-provider.html">Contacts Provider</a> API even if +your app does not include the {@link android.Manifest.permission#READ_CONTACTS} permission.</p> + +<p class="note"><strong>Tip:</strong> If you need access to only a specific piece of contact +information, such as a phone number or email address, instead see the next section about how to +<a href="#PickContactData">select specific contact data</a>.</p> + +<dl> +<dt><b>Action</b></dt> +<dd>{@link android.content.Intent#ACTION_PICK}</dd> + +<dt><b>Data URI Scheme</b></dt> +<dd>None</dd> + +<dt><b>MIME Type</b></dt> +<dd>{@link android.provider.ContactsContract.Contacts#CONTENT_TYPE +Contacts.CONTENT_TYPE} +</dd> +</dl> + +<p><b>Example intent:</b></p> +<pre> +static final int REQUEST_SELECT_CONTACT = 1; + +public void selectContact() { + Intent intent = new Intent(Intent.ACTION_PICK); + intent.setType(ContactsContract.Contacts.CONTENT_TYPE); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivityForResult(intent, REQUEST_SELECT_CONTACT); + } +} + +@Override +protected void onActivityResult(int requestCode, int resultCode, Intent data) { + if (requestCode == REQUEST_SELECT_CONTACT && resultCode == RESULT_OK) { + Uri contactUri = data.getData(); + // Do something with the selected contact at contactUri + ... + } +} +</pre> + +<p>For information about how to retrieve contact details once you have the contact URI, +read <a href="{@docRoot}training/contacts-provider/retrieve-details.html">Retrieving Details +for a Contact</a>. Remember, when you retrieve the contact URI with the above intent, you +<strong>do not</strong> need the {@link android.Manifest.permission#READ_CONTACTS} permission +to read details for that contact.</p> + + + + +<h3 id="PickContactDat">Select specific contact data</h3> + +<p>To have the user select a specific piece of information from a contact, such as +a phone number, email address, or other data type, use the +{@link android.content.Intent#ACTION_PICK} action and specify the MIME type to one +of the content types listed below, such as +{@link android.provider.ContactsContract.CommonDataKinds.Phone#CONTENT_TYPE +CommonDataKinds.Phone.CONTENT_TYPE} to get the contact's phone number.</p> + +<p>If you need to retrieve only one type of data from a contact, this technique with a +{@code CONTENT_TYPE} from the +{@link android.provider.ContactsContract.CommonDataKinds} classes is more efficient than +using the {@link android.provider.ContactsContract.Contacts#CONTENT_TYPE +Contacts.CONTENT_TYPE} (as shown in the previous section) because the result provides you direct +access to the desired data without requiring you to perform a more complex query to <a +href="{@docRoot}guide/topics/providers/contacts-provider.html">Contacts Provider</a>.</p> + +<p>The result {@link android.content.Intent} delivered to your {@link +android.app.Activity#onActivityResult onActivityResult()} callback contains the +<code>content:</code> URI pointing to the selected contact data. The response grants +your app temporary permissions to read that contact data even if your app does +not include the {@link android.Manifest.permission#READ_CONTACTS} permission.</p> + +<dl> +<dt><b>Action</b></dt> +<dd>{@link android.content.Intent#ACTION_PICK}</dd> + +<dt><b>Data URI Scheme</b></dt> +<dd>None</dd> + +<dt><b>MIME Type</b></dt> +<dd> + <dl> + <dt>{@link android.provider.ContactsContract.CommonDataKinds.Phone#CONTENT_TYPE +CommonDataKinds.Phone.CONTENT_TYPE}</dt> + <dd>Pick from contacts with a phone number.</dd> + <dt>{@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_TYPE +CommonDataKinds.Email.CONTENT_TYPE}</dt> + <dd>Pick from contacts with an email address.</dd> + <dt>{@link android.provider.ContactsContract.CommonDataKinds.StructuredPostal#CONTENT_TYPE +CommonDataKinds.StructuredPostal.CONTENT_TYPE}</dt> + <dd>Pick from contacts with a postal address.</dd> + </dl> + <p>Or one of many other {@code CONTENT_TYPE} values + under {@link android.provider.ContactsContract}.</p> +</dd> +</dl> + +<p><b>Example intent:</b></p> +<pre> +static final int REQUEST_SELECT_PHONE_NUMBER = 1; + +public void selectContact() { + // Start an activity for the user to pick a phone number from contacts + Intent intent = new Intent(Intent.ACTION_PICK); + intent.setType(CommonDataKinds.Phone.CONTENT_TYPE); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivityForResult(intent, REQUEST_SELECT_PHONE_NUMBER); + } +} + +@Override +protected void onActivityResult(int requestCode, int resultCode, Intent data) { + if (requestCode == REQUEST_SELECT_PHONE_NUMBER && resultCode == RESULT_OK) { + // Get the URI and query the content provider for the phone number + Uri contactUri = data.getData(); + String[] projection = new String[]{CommonDataKinds.Phone.NUMBER}; + Cursor cursor = getContentResolver().query(contactUri, projection, + null, null, null); + // If the cursor returned is valid, get the phone number + if (cursor != null && cursor.moveToFirst()) { + int numberIndex = cursor.getColumnIndex(CommonDataKinds.Phone.NUMBER); + String number = cursor.getString(numberIndex); + // Do something with the phone number + ... + } + } +} +</pre> + + + + + +<h3 id="ViewContact">View a contact</h3> + +<p>To display the details for a known contact, use the {@link android.content.Intent#ACTION_VIEW} +action and specify the contact with a {@code content:} URI as the intent data.</p> + +<p>There are primarily two ways to initially retrieve the contact's URI:</p> +<ul> + <li>Use the contact URI returned by the {@link android.content.Intent#ACTION_PICK}, + shown in the previous section (this does not require any app permissions).</li> + <li>Access the list of all contacts directly, as described in <a + href="{@docRoot}training/contacts-provider/retrieve-names.html">Retrieving a List of + Contacts</a> (this requires the {@link android.Manifest.permission#READ_CONTACTS} + permission).</li> +</ul> + +<dl> +<dt><b>Action</b></dt> +<dd>{@link android.content.Intent#ACTION_VIEW}</dd> + +<dt><b>Data URI Scheme</b></dt> +<dd>{@code content:<URI>}</dd> + +<dt><b>MIME Type</b></dt> +<dd>None. The type is inferred from contact URI. +</dd> +</dl> + +<p><b>Example intent:</b></p> +<pre> +public void viewContact(Uri contactUri) { + Intent intent = new Intent(Intent.ACTION_VIEW, contactUri); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivity(intent); + } +} +</pre> + + + +<h3 id="EditContact">Edit an existing contact</h3> + +<p>To edit a known contact, use the {@link android.content.Intent#ACTION_EDIT} +action, specify the contact with a {@code content:} URI +as the intent data, and include any known contact information in extras specified by +constants in {@link android.provider.ContactsContract.Intents.Insert}.</p> + +<p>There are primarily two ways to initially retrieve the contact URI:</p> +<ul> + <li>Use the contact URI returned by the {@link android.content.Intent#ACTION_PICK}, + shown in the previous section (this does not require any app permissions).</li> + <li>Access the list of all contacts directly, as described in <a + href="{@docRoot}training/contacts-provider/retrieve-names.html">Retrieving a List of + Contacts</a> (this requires the {@link android.Manifest.permission#READ_CONTACTS} + permission).</li> +</ul> + +<dl> +<dt><b>Action</b></dt> +<dd>{@link android.content.Intent#ACTION_EDIT}</dd> + +<dt><b>Data URI Scheme</b></dt> +<dd>{@code content:<URI>}</dd> + +<dt><b>MIME Type</b></dt> +<dd>The type is inferred from contact URI. +</dd> + +<dt><b>Extras</b> (optional)</dt> +<dd>One or more of the extras defined in {@link android.provider.ContactsContract.Intents.Insert} +so you can populate fields of the contact details. +</dd> +</dl> + +<p><b>Example intent:</b></p> +<pre> +public void editContact(Uri contactUri, String email) { + Intent intent = new Intent(Intent.ACTION_EDIT); + intent.setDataAndType(contactUri, Contacts.CONTENT_TYPE); + intent.putExtra(Intents.Insert.EMAIL, email); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivity(intent); + } +} +</pre> + +<p>For more information about how to edit a contact, read <a +href="{@docRoot}training/contacts-provider/modify-data.html">Modifying +Contacts Using Intents</a>.</p> + + + + +<h3 id="InsertContact">Insert a contact</h3> + +<p>To insert a new contact, use the {@link android.content.Intent#ACTION_INSERT} action, +specify {@link android.provider.ContactsContract.Contacts#CONTENT_TYPE Contacts.CONTENT_TYPE} as +the MIME type, and include any known contact information in extras specified by +constants in {@link android.provider.ContactsContract.Intents.Insert}. + +<dl> +<dt><b>Action</b></dt> +<dd>{@link android.content.Intent#ACTION_INSERT}</dd> + +<dt><b>Data URI Scheme</b></dt> +<dd>None</dd> + +<dt><b>MIME Type</b></dt> +<dd>{@link android.provider.ContactsContract.Contacts#CONTENT_TYPE Contacts.CONTENT_TYPE}</dd> + +<dt><b>Extras</b> (optional)</dt> +<dd>One or more of the extras defined in {@link android.provider.ContactsContract.Intents.Insert}. +</dd> +</dl> + +<p><b>Example intent:</b></p> +<pre> +public void insertContact(String name, String email) { + Intent intent = new Intent(Intent.ACTION_INSERT); + intent.setType(Contacts.CONTENT_TYPE); + intent.putExtra(Intents.Insert.NAME, name); + intent.putExtra(Intents.Insert.EMAIL, email); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivity(intent); + } +} +</pre> + +<p>For more information about how to insert a contact, read <a +href="{@docRoot}training/contacts-provider/modify-data.html">Modifying +Contacts Using Intents</a>.</p> + + + + + + + +<h2 id="Email">Email</h2> + + +<h3 id="ComposeEmail">Compose an email with optional attachments</h3> + + +<p>To compose an email, use one of the below actions based on whether you'll include attachments, +and include email details such as the recipient and subject using the extra keys listed below.</p> + +<dl> +<dt><b>Action</b></dt> +<dd>{@link android.content.Intent#ACTION_SENDTO} (for no attachment) or<br> + {@link android.content.Intent#ACTION_SEND} (for one attachment) or<br> + {@link android.content.Intent#ACTION_SEND_MULTIPLE} (for multiple attachments)</dd> + +<dt><b>Data URI Scheme</b></dt> +<dd>None</dd> + +<dt><b>MIME Type</b></dt> +<dd> + <dl> + <dt>{@link org.apache.http.protocol.HTTP#PLAIN_TEXT_TYPE} ("text/plain") + <dt><code>"*/*"</code> + </dl> +</dd> + +<dt><b>Extras</b> (optional)</dt> +<dd> + <dl> + <dt>{@link android.content.Intent#EXTRA_EMAIL Intent.EXTRA_EMAIL}</dt> + <dd>A string array of all "To" recipient email addresses.</dd> + <dt>{@link android.content.Intent#EXTRA_CC Intent.EXTRA_CC}</dt> + <dd>A string array of all "CC" recipient email addresses.</dd> + <dt>{@link android.content.Intent#EXTRA_BCC Intent.EXTRA_BCC}</dt> + <dd>A string array of all "BCC" recipient email addresses.</dd> + <dt>{@link android.content.Intent#EXTRA_SUBJECT Intent.EXTRA_SUBJECT}</dt> + <dd>A string with the email subject.</dd> + <dt>{@link android.content.Intent#EXTRA_TEXT Intent.EXTRA_TEXT}</dt> + <dd>A string with the body of the email.</dd> + <dt>{@link android.content.Intent#EXTRA_STREAM Intent.EXTRA_STREAM}</dt> + <dd>A {@link android.net.Uri} pointing to the attachment. If using the + {@link android.content.Intent#ACTION_SEND_MULTIPLE} action, this should instead + be an {@link java.util.ArrayList} containing multiple {@link android.net.Uri} objects.</dd> + </dl> +</dd> + +</dl> + + +<p><b>Example intent:</b></p> +<pre> +public void composeEmail(String[] addresses, String subject, Uri attachment) { + Intent intent = new Intent(Intent.ACTION_SEND); + intent.setType("*/*"); + intent.putExtra(Intent.EXTRA_EMAIL, addresses); + intent.putExtra(Intent.EXTRA_SUBJECT, subject); + intent.putExtra(Intent.EXTRA_STREAM, attachment); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivity(intent); + } +} +</pre> + +<p>If you want to ensure that your intent is handled only by an email app (and not other +text messaging or social apps), then use the {@link android.content.Intent#ACTION_SENDTO} action +and include the {@code "mailto:"} data scheme. For example:</p> + +<pre> +public void composeEmail(String[] addresses, String subject) { + Intent intent = new Intent(Intent.ACTION_SENDTO); + intent.setData(Uri.parse("mailto:")); // only email apps should handle this + intent.putExtra(Intent.EXTRA_EMAIL, addresses); + intent.putExtra(Intent.EXTRA_SUBJECT, subject); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivity(intent); + } +} +</pre> + + +<p><b>Example intent filter:</b></p> +<pre> +<activity ...> + <intent-filter> + <action android:name="android.intent.action.SEND" /> + <data android:type="*/*" /> + <category android:name="android.intent.category.DEFAULT" /> + </intent-filter> + <intent-filter> + <action android:name="android.intent.action.SENDTO" /> + <data android:scheme="mailto" /> + <category android:name="android.intent.category.DEFAULT" /> + </intent-filter> +</activity> +</pre> + + + + + + + + + + + + + + + + +<h2 id="Storage">File Storage</h2> + + + +<h3 id="GetFile">Retrieve a specific type of file</h3> + +<p>To request that the user select a file such as a document or photo and return a reference to +your app, use the {@link android.content.Intent#ACTION_GET_CONTENT} action and specify your desired +MIME type. The file reference returned to your app is transient to your activity's current +lifecycle, so if you want to access it later you must import a copy that you can read later. +This intent also allows the user to create a new file in the process (for +example, instead of selecting an existing photo, the user can capture a new photo with the camera). +</p> + +<p>The result intent delivered to your {@link android.app.Activity#onActivityResult +onActivityResult()} method includes data with a URI pointing to the file. +The URI could be anything, such as an {@code http:} URI, {@code file:} URI, or {@code content:} +URI. However, if you'd like to restrict selectable files to only those that are accessible +from a content provider (a {@code content:} URI) and that are available as a file stream with {@link +android.content.ContentResolver#openFileDescriptor openFileDescriptor()}, you should add +the {@link android.content.Intent#CATEGORY_OPENABLE} category to your intent.</p> + +<p>On Android 4.3 (API level 18) and higher, +you can also allow the user to select multiple files by adding +{@link android.content.Intent#EXTRA_ALLOW_MULTIPLE} to the intent, set to {@code true}. +You can then access each of the selected files in a {@link android.content.ClipData} +object returned by {@link android.content.Intent#getClipData()}.</p> + + +<dl> +<dt><b>Action</b></dt> +<dd>{@link android.content.Intent#ACTION_GET_CONTENT}</dd> + +<dt><b>Data URI Scheme</b></dt> +<dd>None</dd> + +<dt><b>MIME Type</b></dt> +<dd>The MIME type corresponding to the file type the user should select. +</dd> + +<dt><b>Extras</b> (optional)</dt> +<dd> + <dl> + <dt>{@link android.content.Intent#EXTRA_ALLOW_MULTIPLE} + <dd>A boolean declaring whether the user can select more than one file at a time. + </dd> + <dt>{@link android.content.Intent#EXTRA_LOCAL_ONLY} + <dd>A boolean that declares whether the returned file must be available directly from + the device, rather than requiring a download from a remote service. + </dd> + </dl> +</dd> + +<dt><b>Category</b> (optional)</dt> +<dd> + <dl> + <dt>{@link android.content.Intent#CATEGORY_OPENABLE}</dt> + <dd>To return only "openable" files that can be represented as a file stream + with {@link android.content.ContentResolver#openFileDescriptor openFileDescriptor()}.</dd> + </dl> +</dd> + +</dl> + +<p><b>Example intent to get a photo:</b></p> +<pre> +static final int REQUEST_IMAGE_GET = 1; + +public void selectImage() { + Intent intent = new Intent(Intent.ACTION_GET_CONTENT); + intent.setType("image/*"); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivityForResult(intent, REQUEST_IMAGE_GET); + } +} + +@Override +protected void onActivityResult(int requestCode, int resultCode, Intent data) { + if (requestCode == REQUEST_IMAGE_GET && resultCode == RESULT_OK) { + Bitmap thumbnail = data.getParcelable("data"); + Uri fullPhotoUri = data.getData(); + // Do work with photo saved at fullPhotoUri + ... + } +} +</pre> + +<p><b>Example intent filter to return a photo:</b></p> +<pre> +<activity ...> + <intent-filter> + <action android:name="android.intent.action.GET_CONTENT" /> + <data android:type="image/*" /> + <category android:name="android.intent.category.DEFAULT" /> + <!-- The OPENABLE category declares that the returned file is accessible + from a content provider that supports {@link android.provider.OpenableColumns} + and {@link android.content.ContentResolver#openFileDescriptor ContentResolver.openFileDescriptor()} --> + <category android:name="android.intent.category.OPENABLE" /> + </intent-filter> +</activity> +</pre> + + + + + + +<h3 id="OpenFile">Open a specific type of file</h3> + +<p>Instead of retrieving a copy of a file that you must import to your app +(by using the {@link android.content.Intent#ACTION_GET_CONTENT} action), when running on Android +4.4 or higher, you can instead request to <em>open</em> a file that's managed by another app by +using the {@link android.content.Intent#ACTION_OPEN_DOCUMENT} action and specifying a MIME type. +To also allow the user to instead create a new document that your app can write to, use the {@link +android.content.Intent#ACTION_CREATE_DOCUMENT} action instead. For example, instead of +selecting from existing PDF documents, the {@link android.content.Intent#ACTION_CREATE_DOCUMENT} +intent allows users to select where they'd like to create a new document (within another app +that manages the document's storage)—your app then receives the URI location of where it +can write the new document.</p> + +<p>Whereas the intent delivered to your {@link android.app.Activity#onActivityResult +onActivityResult()} method from the {@link android.content.Intent#ACTION_GET_CONTENT} action may +return a URI of any type, the result intent from {@link android.content.Intent#ACTION_OPEN_DOCUMENT} +and {@link android.content.Intent#ACTION_CREATE_DOCUMENT} always specify the chosen file as a {@code +content:} URI that's backed by a {@link android.provider.DocumentsProvider}. You can open the +file with {@link android.content.ContentResolver#openFileDescriptor openFileDescriptor()} and +query its details using columns from {@link android.provider.DocumentsContract.Document}.</p> + +<p>The returned URI grants your app long-term read access to the file (also possibly +with write access). So the {@link android.content.Intent#ACTION_OPEN_DOCUMENT} action is +particularly useful (instead of using {@link android.content.Intent#ACTION_GET_CONTENT}) +when you want to read an existing file without making a copy into your app, +or when you want to open and edit a file in place.</p> + +<p>You can also allow the user to select multiple files by adding +{@link android.content.Intent#EXTRA_ALLOW_MULTIPLE} to the intent, set to {@code true}. +If the user selects just one item, then you can retrieve the item from {@link +android.content.Intent#getData()}. If the user selects more than one item, then {@link +android.content.Intent#getData()} returns null and you must instead +retrieve each item from a {@link android.content.ClipData} +object that is returned by {@link android.content.Intent#getClipData()}.</p> + +<p class="note"><strong>Note:</strong> Your intent <strong>must</strong> specify a MIME type and +<strong>must</strong> declare the {@link android.content.Intent#CATEGORY_OPENABLE} category. If +appropriate, you can specify more than one MIME type by adding an array of MIME types with the +{@link android.content.Intent#EXTRA_MIME_TYPES} extra—if you do so, you must set the +primary MIME type in {@link android.content.Intent#setType setType()} to {@code "*/*"}.</p> + +<dl> +<dt><b>Action</b></dt> +<dd>{@link android.content.Intent#ACTION_OPEN_DOCUMENT} or<br/> +{@link android.content.Intent#ACTION_CREATE_DOCUMENT}</dd> + +<dt><b>Data URI Scheme</b></dt> +<dd>None</dd> + +<dt><b>MIME Type</b></dt> +<dd>The MIME type corresponding to the file type the user should select. +</dd> + +<dt><b>Extras</b> (optional)</dt> +<dd> + <dl> + <dt>{@link android.content.Intent#EXTRA_MIME_TYPES} + <dd>An array of MIME types corresponding to the types of files your app is + requesting. When you use this extra, you must set the primary MIME type in + {@link android.content.Intent#setType setType()} to {@code "*/*"}.</dd> + <dt>{@link android.content.Intent#EXTRA_ALLOW_MULTIPLE} + <dd>A boolean that declares whether the user can select more than one file at a time. + </dd> + <dt>{@link android.content.Intent#EXTRA_TITLE} + <dd>For use with {@link android.content.Intent#ACTION_CREATE_DOCUMENT} to specify + an initial file name. + </dd> + <dt>{@link android.content.Intent#EXTRA_LOCAL_ONLY} + <dd>A boolean that declares whether the returned file must be available directly from + the device, rather than requiring a download from a remote service. + </dd> + </dl> +</dd> + +<dt><b>Category</b></dt> +<dd> + <dl> + <dt>{@link android.content.Intent#CATEGORY_OPENABLE}</dt> + <dd>To return only "openable" files that can be represented as a file stream + with {@link android.content.ContentResolver#openFileDescriptor openFileDescriptor()}.</dd> + </dl> +</dd> + +</dl> + +<p><b>Example intent to get a photo:</b></p> +<pre> +static final int REQUEST_IMAGE_OPEN = 1; + +public void selectImage() { + Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT); + intent.setType("image/*"); + intent.addCategory(Intent.CATEGORY_OPENABLE); + // Only the system receives the ACTION_OPEN_DOCUMENT, so no need to test. + startActivityForResult(intent, REQUEST_IMAGE_OPEN); +} + +@Override +protected void onActivityResult(int requestCode, int resultCode, Intent data) { + if (requestCode == REQUEST_IMAGE_OPEN && resultCode == RESULT_OK) { + Uri fullPhotoUri = data.getData(); + // Do work with full size photo saved at fullPhotoUri + ... + } +} +</pre> + +<p>Third party apps cannot actually respond to an intent with the +{@link android.content.Intent#ACTION_OPEN_DOCUMENT} action. Instead, the system receives this +intent and displays all the files available from various apps in a unified user interface.</p> + +<p>To provide your app's files in this UI and allow other apps to open them, you must implement +a {@link android.provider.DocumentsProvider} and include an intent filter for +{@link android.provider.DocumentsContract#PROVIDER_INTERFACE} +({@code "android.content.action.DOCUMENTS_PROVIDER"}). For example: + +<pre> +<provider ... + android:grantUriPermissions="true" + android:exported="true" + android:permission="android.permission.MANAGE_DOCUMENTS"> + <intent-filter> + <action android:name="android.content.action.DOCUMENTS_PROVIDER" /> + </intent-filter> +</provider> +</pre> + +<p>For more information about how to make the files managed by your app openable from other apps, +read the <a href="{@docRoot}guide/topics/providers/document-provider.html">Storage Access +Framework</a> guide.</p> + + + + + + + + + + + +<h2 id="Maps">Maps</h2> + +<h3 id="ViewMap">Show a location on a map</h3> + +<p>To open a map, use the {@link android.content.Intent#ACTION_VIEW} action and specify +the location information in the intent data with one of the schemes defined below.</p> + +<dl> +<dt><b>Action</b></dt> +<dd>{@link android.content.Intent#ACTION_VIEW}</dd> + +<dt><b>Data URI Scheme</b></dt> +<dd> +<dl> + <dt><code>geo:<em>latitude</em>,<em>longitude</em></code></dt> + <dd>Show the map at the given longitude and latitude. + <p>Example: <code>"geo:47.6,-122.3"</code> + </dd> + <dt><code>geo:<em>latitude</em>,<em>longitude</em>?z=<em>zoom</em></code></dt> + <dd>Show the map at the given longitude and latitude at a certain zoom level. A zoom level of + 1 shows the whole Earth, centered at the given <em>lat</em>,<em>lng</em>. The highest + (closest) zoom level is 23. + <p>Example: <code>"geo:47.6,-122.3?z=11"</code> + </dd> + <dt><code>geo:0,0?q=lat,lng(label)</code></dt> + <dd>Show the map at the given longitude and latitude with a string label. + <p>Example: <code>"geo:0,0?q=34.99,-106.61(Treasure)"</code> + </dd> + <dt><code>geo:0,0?q=my+street+address</code></dt> + <dd>Show the location for "my street address" (may be a specific address or location query). + <p>Example: <code>"geo:0,0?q=1600+amphitheatre+parkway+ca"</code> + </dd> +</dl> +</dd> + +<dt><b>MIME Type</b></dt> +<dd>None</dd> + +</dl> + +<p><b>Example intent:</b></p> +<pre> +public void showMap(Uri geoLocation) { + Intent intent = new Intent(Intent.ACTION_VIEW); + intent.setData(geoLocation); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivity(intent); + } +} +</pre> + +<p><b>Example intent filter:</b></p> +<pre> +<activity ...> + <intent-filter> + <action android:name="android.intent.action.VIEW" /> + <data android:scheme="geo" /> + <category android:name="android.intent.category.DEFAULT" /> + </intent-filter> +</activity> +</pre> + + + + + + + + +<h2 id="Music">Music or Video</h2> + + +<h3 id="PlayMedia">Play a media file</h3> + +<p>To play a music file, use the {@link android.content.Intent#ACTION_VIEW} action and +specify the URI location of the file in the intent data.</p> + +<dl> +<dt><b>Action</b></dt> +<dd>{@link android.content.Intent#ACTION_VIEW}</dd> + +<dt><b>Data URI Scheme</b></dt> +<dd> + <dl> + <dt>{@code file:<em><URI></em>} + <dt>{@code content:<em><URI></em>} + <dt>{@code http:<em><URL></em>} + </dl> +</dd> + +<dt><b>MIME Type</b></dt> +<dd> + <dl> + <dt><code>"audio/*"</code> + <dt><code>"application/ogg"</code> + <dt><code>"application/x-ogg"</code> + <dt><code>"application/itunes"</code> + <dt>Or any other that your app may require. + </dl> +</dd> + +</dl> + +<p><b>Example intent:</b></p> +<pre> +public void playMedia(Uri file) { + Intent intent = new Intent(Intent.ACTION_VIEW); + intent.setData(file); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivity(intent); + } +} +</pre> + + +<p><b>Example intent filter:</b></p> +<pre> +<activity ...> + <intent-filter> + <action android:name="android.intent.action.VIEW" /> + <data android:type="audio/*" /> + <data android:type="application/ogg" /> + <category android:name="android.intent.category.DEFAULT" /> + </intent-filter> +</activity> +</pre> + + + + + + + + +<h2 id="Phone">Phone</h2> + + +<h3 id="DialPhone">Initiate a phone call</h3> + +<p>To open the phone app and dial a phone number, use the {@link +android.content.Intent#ACTION_DIAL} action and specify a phone number using +the URI scheme defined below. When the phone app opens, it displays the phone number +but the user must press the <em>Call</em> button to begin the phone call.</p> + + +<dl> +<dt><b>Action</b></dt> +<dd>{@link android.content.Intent#ACTION_DIAL}</dd> + +<dt><b>Data URI Scheme</b></dt> +<dd>{@code tel:<phone-number>}</dd> + +<dt><b>MIME Type</b></dt> +<dd>None</dd> + +</dl> + + +<p>Valid telephone numbers are those defined +in <a href="http://tools.ietf.org/html/rfc3966">the IETF RFC 3966</a>. +Valid examples include the following:</p> +<ul> +<li><code>tel:2125551212</code> </li> +<li><code>tel:(212) 555 1212</code></li> +</ul> +<p>The Phone's dialer is good at normalizing schemes, such as +telephone numbers. So the scheme described isn't strictly required in the +{@link android.net.Uri#parse(String) Uri.parse()} method. +However, if you have not tried a scheme or are unsure whether it +can be handled, use the {@link android.net.Uri#fromParts Uri.fromParts()} +method instead.</p> + + +<p><b>Example intent:</b></p> +<pre> +public void dialPhoneNumber(String phoneNumber) { + Intent intent = new Intent(Intent.ACTION_DIAL); + intent.setData(Uri.parse("tel:" + phoneNumber)); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivity(intent); + } +} +</pre> + + + + + + + + + + +<h2 id="Settings">Settings</h2> + +<h3 id="OpenSettings">Open a specific section of Settings</h3> + +<p>To open a screen in the system settings when your app requires the user to change something, +use one of the following intent actions to open the settings screen respective to the action name. +</p> + +<dl> +<dt><b>Action</b></dt> +<dd> +{@link android.provider.Settings#ACTION_SETTINGS}<br/> +{@link android.provider.Settings#ACTION_WIRELESS_SETTINGS}<br/> +{@link android.provider.Settings#ACTION_AIRPLANE_MODE_SETTINGS}<br/> +{@link android.provider.Settings#ACTION_WIFI_SETTINGS}<br/> +{@link android.provider.Settings#ACTION_APN_SETTINGS}<br/> +{@link android.provider.Settings#ACTION_BLUETOOTH_SETTINGS}<br/> +{@link android.provider.Settings#ACTION_DATE_SETTINGS}<br/> +{@link android.provider.Settings#ACTION_LOCALE_SETTINGS}<br/> +{@link android.provider.Settings#ACTION_INPUT_METHOD_SETTINGS}<br/> +{@link android.provider.Settings#ACTION_DISPLAY_SETTINGS}<br/> +{@link android.provider.Settings#ACTION_SECURITY_SETTINGS}<br/> +{@link android.provider.Settings#ACTION_LOCATION_SOURCE_SETTINGS}<br/> +{@link android.provider.Settings#ACTION_INTERNAL_STORAGE_SETTINGS}<br/> +{@link android.provider.Settings#ACTION_MEMORY_CARD_SETTINGS}<br/> +<p>See the {@link android.provider.Settings} documentation for additional settings screens +that are available.</p> +</dd> + +<dt><b>Data URI Scheme</b></dt> +<dd>None</dd> + +<dt><b>MIME Type</b></dt> +<dd>None</dd> + +</dl> + +<p><b>Example intent:</b></p> +<pre> +public void openWifiSettings() { + Intent intent = new Intent(Intent.ACTION_WIFI_SETTINGS); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivity(intent); + } +} +</pre> + + + + + + + +<h2 id="Messaging">Text Messaging</h2> + +<h3 id="SendMessage">Compose an SMS/MMS message with attachment</h3> + +<p>To initiate an SMS or MMS text message, use one of the intent actions below and specify message +details such as the phone number, subject, and message body using the extra keys listed below.</p> + +<dl> +<dt><b>Action</b></dt> +<dd>{@link android.content.Intent#ACTION_SENDTO} or<br> + {@link android.content.Intent#ACTION_SEND} or<br> + {@link android.content.Intent#ACTION_SEND_MULTIPLE}</dd> + +<dt><b>Data URI Scheme</b></dt> +<dd> + <dl> + <dt>{@code sms:<em><phone_number></em>} + <dt>{@code smsto:<em><phone_number></em>} + <dt>{@code mms:<em><phone_number></em>} + <dt>{@code mmsto:<em><phone_number></em>} + </dl> + <p>Each of these schemes are handled the same. +</dd> + +<dt><b>MIME Type</b></dt> +<dd> + <dl> + <dt>{@link org.apache.http.protocol.HTTP#PLAIN_TEXT_TYPE} (<code>"text/plain"</code>) + <dt><code>"image/*"</code> + <dt><code>"video/*"</code> + </dl> +</dd> + +<dt><b>Extras</b> (optional)</dt> +<dd> + <dl> + <dt><code>"subject"</code></dt> + <dd>A string for the message subject (usually for MMS only).</dd> + <dt><code>"sms_body"</code></dt> + <dd>A string for the text message.</dd> + <dt>{@link android.content.Intent#EXTRA_STREAM}</dt> + <dd>A {@link android.net.Uri} pointing to the +image or video to attach. If using the {@link android.content.Intent#ACTION_SEND_MULTIPLE} action, +this extra should be an {@link java.util.ArrayList} of {@link +android.net.Uri}s pointing to the images/videos to attach.</dd> + <dl> +</dd> + +</dl> + +<p><b>Example intent:</b></p> +<pre> +public void composeMmsMessage(String message, Uri attachment) { + Intent intent = new Intent(Intent.ACTION_SEND); + intent.setType(HTTP.PLAIN_TEXT_TYPE); + intent.putExtra("sms_body", message); + intent.putExtra(Intent.EXTRA_STREAM, attachment); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivity(intent); + } +} +</pre> + +<p>If you want to ensure that your intent is handled only by a text messaging app (and not other +email or social apps), then use the {@link android.content.Intent#ACTION_SENDTO} action +and include the {@code "smsto:"} data scheme. For example:</p> + +<pre> +public void composeMmsMessage(String message, Uri attachment) { + Intent intent = new Intent(Intent.ACTION_SEND); + intent.setData(Uri.parse("smsto:")); // This ensures only SMS apps respond + intent.putExtra("sms_body", message); + intent.putExtra(Intent.EXTRA_STREAM, attachment); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivity(intent); + } +} +</pre> + + +<p><b>Example intent filter:</b></p> +<pre> +<activity ...> + <intent-filter> + <action android:name="android.intent.action.SEND" /> + <data android:type="text/plain" /> + <data android:type="image/*" /> + <category android:name="android.intent.category.DEFAULT" /> + </intent-filter> +</activity> +</pre> + +<p class="note"><strong>Note:</strong> If you're developing an SMS/MMS messaging app, you must +implement intent filters for several additional actions in order to be available as the +<em>default SMS app</em> on Android 4.4 and higher. For more information, see the documentation +at {@link android.provider.Telephony}.</p> + + + + + + + + + + +<h2 id="Browser">Web Browser</h2> + +<h3 id="ViewUrl">Load a web URL</h3> + +<p>To open a web page, use the {@link android.content.Intent#ACTION_VIEW} action +and specify the web URL in the intent data.</p> + +<dl> + <dt><b>Action</b></dt> + <dd>{@link android.content.Intent#ACTION_VIEW}<dd> + + <dt><b>Data URI Scheme</b></dt> + <dd>{@code http:<em><URL></em>}<br/> + {@code https:<em><URL></em>}</dd> + + <dt><b>MIME Type</b></dt> + <dd> + <dl> + <dt>{@link org.apache.http.protocol.HTTP#PLAIN_TEXT_TYPE} (<code>"text/plain"</code>) + <dt><code>"text/html"</code> + <dt><code>"application/xhtml+xml"</code> + <dt><code>"application/vnd.wap.xhtml+xml"</code> + </dl> + </dd> +</dl> + + +<p><b>Example intent:</b></p> +<pre> +public void openWebPage(String url) { + Uri webpage = Uri.parse(url); + Intent intent = new Intent(Intent.ACTION_VIEW, webpage); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivity(intent); + } +} +</pre> + + +<p><b>Example intent filter:</b></p> +<pre> +<activity ...> + <intent-filter> + <action android:name="android.intent.action.VIEW" /> + <!-- Include the host attribute if you want your app to respond + only to URLs with your app's domain. --> + <data android:scheme="http" android:host="www.example.com" /> + <category android:name="android.intent.category.DEFAULT" /> + <!-- The BROWSABLE category is required to get links from web pages. --> + <category android:name="android.intent.category.BROWSABLE" /> + </intent-filter> +</activity> +</pre> + + +<p class="note"><strong>Tip:</strong> If your Android app provides functionality similar to +your web site, include an intent filter for URLs that point to your web site. Then, +if users have your app installed, links from emails or other web pages pointing to your web site +open your Android app instead of your web page.</p> + + + + +<h3 id="SearchWeb">Perform a web search</h3> + +<p>To initiate a web search, use the {@link android.content.Intent#ACTION_WEB_SEARCH} action +and specify the search string in the +{@link android.app.SearchManager#QUERY SearchManager.QUERY} extra.</p> + + +<dl> + <dt><b>Action</b></dt> + <dd>{@link android.content.Intent#ACTION_WEB_SEARCH}</dd> + + <dt><b>Data URI Scheme</b></dt> + <dd>None</dd> + + <dt><b>MIME Type</b></dt> + <dd>None</dd> + + <dt><b>Extras</b></dt> + <dd> + <dl> + <dt>{@link android.app.SearchManager#QUERY SearchManager.QUERY}</dt> + <dd>The search string.</dd> + </dl> + </dd> +</dl> + +<p><b>Example intent:</b></p> +<pre> +public void searchWeb(String query) { + Intent intent = new Intent(Intent.ACTION_SEARCH); + intent.putExtra(SearchManager.QUERY, query); + if (intent.resolveActivity(getPackageManager()) != null) { + startActivity(intent); + } +} +</pre> + + + |