Android API Guides---Common Intents

一个意图可以让你通过描述一个简单的动作，你想执行（如“查看地图”或“拍照”）的一个Intent对象，开始在另一个应用程序的活动。这种类型的意图被称为隐含的意图，因为它没有指定的应用程序组件开始，而是指定了一个动作，并提供了一​​些数据，用以执行的操作。


当你调用startActivity（）或startActivityForResult（），并通过它的一个隐含的意图，该系统解决了意图的应用程序，可以处理这个意图并开始相应的活动。如果有一个以上的应用程序，可以处理这个意图，系统显示一个对话框，用户挑选使用哪个应用程序。


此页面介绍了可用于执行共同行动，通过处理该意图的应用类型组织了多次隐含意图。每个部分还展示了如何创建一个意图过滤器来宣传您的应用程序的执行相同的操作能力。


注意：如果有可以接收隐含意图在设备上安装任何应用，当它调用startActivity您的应用程序会崩溃（）。首先验证一个应用程序是否存在接收的意图，你的意图对象调用resolveActivity（）。如果结果是非空，至少有一个应用程序能够处理的意图和它的安全调用startActivity（）。如果结果为空，你不应该使用的意图，可能的话，你应该禁用调用的意图的功能。


如果你不熟悉如何创建意图或意图过滤器，您应该先阅读意图和意图过滤器。


要了解如何激发您的开发主机此页面上列出的意图，请参阅验证了Android调试桥意图

Google Now

谷歌现在有些触发响应语音命令在此页面上列出的意图的。欲了解更多信息，请参阅谷歌解雇现在意图

Alarm Clock

Create an alarm

Google Now

• "set an alarm for 7 am"

要创建一个新的警报，使用ACTION_SET_ALARM行动，并指定报警的详细信息，如下面定义的时间和使用消息临时演员。
注意：只有小时，分钟和额外的消息在的Andr​​oid 2.3（API等级9）和更高可用。在该平台的后续版本中添加了其他额外。

Action
ACTION_SET_ALARM
数据URI
没有
MIME类型
没有
extra
EXTRA_HOUR
报警的时间。
EXTRA_MINUTES
该分钟报警。
EXTRA_MESSAGE
自定义消息，识别报警。
EXTRA_DAYS
一个ArrayList包括每周日要在其上重复此警报。每天必须从Calendar类，如周一整数声明。
对于一次性报警，不指定该额外费用。
EXTRA_RINGTONE
内容：URI指定一个铃声，闹铃或价值RINGTONE沉默不铃声使用。
要使用默认的铃声，不指定该额外费用。
EXTRA_VIBRATE
一个布尔值指定是否为此报警振动。
EXTRA SKIP UI
一个布尔值，指定设置报警时响应的应用程​​序是否应该跳过它的UI。如果为true，应用程序应该绕过任何确认的用户界面和简单的设置指定的报警。
举例意图：

public void createAlarm(String message, int hour, int minutes) {
    Intent intent = new Intent(AlarmClock.ACTION_SET_ALARM)
            .putExtra(AlarmClock.EXTRA_MESSAGE, message)
            .putExtra(AlarmClock.EXTRA_HOUR, hour)
            .putExtra(AlarmClock.EXTRA_MINUTES, minutes);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

注意：
为了调用ACTION_SET_ALARM意图，您的应用程序必须有SET_ALARM权限：

<uses-permission android:name="com.android.alarm.permission.SET_ALARM" />

Example intent filter:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.SET_ALARM" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

创建一个定时器
现在谷歌
“5分钟设置计时器”
要创建一个倒数计时器，使用ACTION_SET_TIMER行动，并指定计时器的细节，如使用下面定义的额外时间。
注：此意图是在Android 4.4系统（API级别19）补充道。
action
ACTION_SET_TIMER
数据URI
没有
MIME类型
没有
extra
EXTRA_LENGTH
计时器的长度（秒）。
EXTRA_MESSAGE
自定义消息，以确定定时器。
EXTRA SKIP UI
一个布尔值，指定设置定时器，当响应应用程序是否应该跳过它的UI。如果为true，应用程序应该绕过任何确认的用户界面和简单的启动指定的定时器。

Example intent:

public void startTimer(String message, int seconds) {
    Intent intent = new Intent(AlarmClock.ACTION_SET_TIMER)
            .putExtra(AlarmClock.EXTRA_MESSAGE, message)
            .putExtra(AlarmClock.EXTRA_LENGTH, seconds)
            .putExtra(AlarmClock.EXTRA_SKIP_UI, true);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

注意：
为了调用操作SET_TIMER意图，您的应用程序必须有SET_ALARM权限：

<uses-permission android:name="com.android.alarm.permission.SET_ALARM" />

Example intent filter:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.SET_TIMER" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Show all alarms

To show the list of alarms, use the ACTION_SHOW_ALARMS action.

Although not many apps will invoke this intent (it's primarily used by system apps), any app that behaves as an alarm clock should implement this intent filter and respond by showing the list of current alarms.

Note: This intent was added in Android 4.4 (API level 19).

Action

ACTION_SHOW_ALARMS

Data URI

None

MIME Type

None

Example intent filter:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.SHOW_ALARMS" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Calendar

Add a calendar event

To add a new event to the user's calendar, use the ACTION_INSERT action and specify the data URI withEvents.CONTENT_URI. You can then specify various event details using extras defined below.

Action

ACTION_INSERT

Data URI

Events.CONTENT_URI

MIME Type

"vnd.android.cursor.dir/event"

Extras

EXTRA_EVENT_ALL_DAY

A boolean specifying whether this is an all-day event.

EXTRA_EVENT_BEGIN_TIME

The start time of the event (milliseconds since epoch).

EXTRA_EVENT_END_TIME

The end time of the event (milliseconds since epoch).

TITLE

The event title.

DESCRIPTION

The event description.

EVENT_LOCATION

The event location.

EXTRA_EMAIL

A comma-separated list of email addresses that specify the invitees.

Many more event details can be specified using the constants defined in theCalendarContract.EventsColumns class.

Example intent:

public void addEvent(String title, String location, Calendar begin, Calendar end) {
    Intent intent = new Intent(Intent.ACTION_INSERT)
            .setData(Events.CONTENT_URI)
            .putExtra(Events.TITLE, title)
            .putExtra(Events.EVENT_LOCATION, location)
            .putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, begin)
            .putExtra(CalendarContract.EXTRA_EVENT_END_TIME, end);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

Example intent filter:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.INSERT" />
        <data android:mimeType="vnd.android.cursor.dir/event" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Camera

Capture a picture or video and return it

To open a camera app and receive the resulting photo or video, use the ACTION_IMAGE_CAPTURE orACTION_VIDEO_CAPTURE action. Also specify the URI location where you'd like the camera to save the photo or video, in the EXTRA_OUTPUT extra.

Action

ACTION_IMAGE_CAPTURE or
ACTION_VIDEO_CAPTURE

Data URI Scheme

None

MIME Type

None

Extras

EXTRA_OUTPUT

The URI location where the camera app should save the photo or video file (as a  Uri object).

When the camera app successfully returns focus to your activity (your app receives the onActivityResult()callback), you can access the photo or video at the URI you specified with the EXTRA_OUTPUT value.

Note: When you use ACTION_IMAGE_CAPTURE to capture a photo, the camera may also return a downscaled copy (a thumbnail) of the photo in the result Intent, saved as a Bitmap in an extra field named "data".

Example intent:

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
        ...
    }
}

For more information about how to use this intent to capture a photo, including how to create an appropriateUri for the output location, read Taking Photos Simply or Taking Videos Simply.

Example intent filter:

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.IMAGE_CAPTURE" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

When handling this intent, your activity should check for the EXTRA_OUTPUT extra in the incoming Intent, then save the captured image or video at the location specified by that extra and call setResult() with an Intentthat includes a compressed thumbnail in an extra named "data".

Start a camera app in still image mode

Google Now

• "take a picture"

To open a camera app in still image mode, use theINTENT_ACTION_STILL_IMAGE_CAMERA action.

Action

INTENT_ACTION_STILL_IMAGE_CAMERA

Data URI Scheme

None

MIME Type

None

Extras

None

Example intent:

public void capturePhoto() {
    Intent intent = new Intent(MediaStore.INTENT_ACTION_STILL_IMAGE_CAMERA);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent);
    }
}

Example intent filter:

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.STILL_IMAGE_CAMERA" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Start a camera app in video mode

Google Now

• "record a video"

To open a camera app in video mode, use theINTENT_ACTION_VIDEO_CAMERA action.

Action

INTENT_ACTION_VIDEO_CAMERA

Data URI Scheme

None

MIME Type

None

Extras

None

Example intent:

public void capturePhoto() {
    Intent intent = new Intent(MediaStore.INTENT_ACTION_VIDEO_CAMERA);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent);
    }
}

Example intent filter:

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.VIDEO_CAMERA" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Contacts/People App

Select a contact

To have the user select a contact and provide your app access to all the contact information, use theACTION_PICK action and specify the MIME type to Contacts.CONTENT_TYPE.

The result Intent delivered to your onActivityResult() callback contains the content: URI pointing to the selected contact. The response grants your app temporary permissions to read that contact using the Contacts Provider API even if your app does not include the READ_CONTACTS permission.

Tip: 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 select specific contact data.

Action

ACTION_PICK

Data URI Scheme

None

MIME Type

Contacts.CONTENT_TYPE

Example intent:

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
        ...
    }
}

For information about how to retrieve contact details once you have the contact URI, read Retrieving Details for a Contact. Remember, when you retrieve the contact URI with the above intent, you do not need theREAD_CONTACTS permission to read details for that contact.

Select specific contact data

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 ACTION_PICK action and specify the MIME type to one of the content types listed below, such as CommonDataKinds.Phone.CONTENT_TYPE to get the contact's phone number.

If you need to retrieve only one type of data from a contact, this technique with a CONTENT_TYPE from theContactsContract.CommonDataKinds classes is more efficient than using the 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 Contacts Provider.

The result Intent delivered to your onActivityResult() callback contains the content: 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 READ_CONTACTS permission.

Action

ACTION_PICK

Data URI Scheme

None

MIME Type

CommonDataKinds.Phone.CONTENT_TYPE

Pick from contacts with a phone number.

CommonDataKinds.Email.CONTENT_TYPE

Pick from contacts with an email address.

CommonDataKinds.StructuredPostal.CONTENT_TYPE

Pick from contacts with a postal address.

Or one of many other CONTENT_TYPE values under ContactsContract.

Example intent:

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
            ...
        }
    }
}

View a contact

To display the details for a known contact, use the ACTION_VIEW action and specify the contact with acontent: URI as the intent data.

There are primarily two ways to initially retrieve the contact's URI:

• Use the contact URI returned by the ACTION_PICK, shown in the previous section (this approach does not require any app permissions).
• Access the list of all contacts directly, as described in Retrieving a List of Contacts (this approach requires the READ_CONTACTS permission).

Action

ACTION_VIEW

Data URI Scheme

content:<URI>

MIME Type

None. The type is inferred from contact URI.

Example intent:

public void viewContact(Uri contactUri) {
    Intent intent = new Intent(Intent.ACTION_VIEW, contactUri);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

Edit an existing contact

To edit a known contact, use the ACTION_EDIT action, specify the contact with a content: URI as the intent data, and include any known contact information in extras specified by constants inContactsContract.Intents.Insert.

There are primarily two ways to initially retrieve the contact URI:

• Use the contact URI returned by the ACTION_PICK, shown in the previous section (this approach does not require any app permissions).
• Access the list of all contacts directly, as described in Retrieving a List of Contacts (this approach requires the READ_CONTACTS permission).

Action

ACTION_EDIT

Data URI Scheme

content:<URI>

MIME Type

The type is inferred from contact URI.

Extras

One or more of the extras defined in  ContactsContract.Intents.Insert so you can populate fields of the contact details.

Example intent:

public void editContact(Uri contactUri, String email) {
    Intent intent = new Intent(Intent.ACTION_EDIT);
    intent.setData(contactUri);
    intent.putExtra(Intents.Insert.EMAIL, email);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

For more information about how to edit a contact, read Modifying Contacts Using Intents.

Insert a contact

To insert a new contact, use the ACTION_INSERT action, specify Contacts.CONTENT_TYPE as the MIME type, and include any known contact information in extras specified by constants in ContactsContract.Intents.Insert.

Action

ACTION_INSERT

Data URI Scheme

None

MIME Type

Contacts.CONTENT_TYPE

Extras

One or more of the extras defined in  ContactsContract.Intents.Insert.

Example intent:

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);
    }
}

For more information about how to insert a contact, read Modifying Contacts Using Intents.

Email

Compose an email with optional attachments

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.

Action

ACTION_SENDTO (for no attachment) or
ACTION_SEND (for one attachment) or
ACTION_SEND_MULTIPLE (for multiple attachments)

Data URI Scheme

None

MIME Type

"text/plain"

"*/*"

Extras

Intent.EXTRA_EMAIL

A string array of all "To" recipient email addresses.

Intent.EXTRA_CC

A string array of all "CC" recipient email addresses.

Intent.EXTRA_BCC

A string array of all "BCC" recipient email addresses.

Intent.EXTRA_SUBJECT

A string with the email subject.

Intent.EXTRA_TEXT

A string with the body of the email.

Intent.EXTRA_STREAM

A  Uri pointing to the attachment. If using the  ACTION_SEND_MULTIPLE action, this should instead be an  ArrayList containing multiple  Uri objects.

Example intent:

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);
    }
}

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 ACTION_SENDTO action and include the "mailto:" data scheme. For example:

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);
    }
}

Example intent filter:

<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>

File Storage

Retrieve a specific type of file

To request that the user select a file such as a document or photo and return a reference to your app, use theACTION_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).

The result intent delivered to your onActivityResult() method includes data with a URI pointing to the file. The URI could be anything, such as an http: URI, file: URI, or content: URI. However, if you'd like to restrict selectable files to only those that are accessible from a content provider (a content: URI) and that are available as a file stream with openFileDescriptor(), you should add the CATEGORY_OPENABLE category to your intent.

On Android 4.3 (API level 18) and higher, you can also allow the user to select multiple files by addingEXTRA_ALLOW_MULTIPLE to the intent, set to true. You can then access each of the selected files in a ClipDataobject returned by getClipData().

Action

ACTION_GET_CONTENT

Data URI Scheme

None

MIME Type

The MIME type corresponding to the file type the user should select.

Extras

EXTRA_ALLOW_MULTIPLE

A boolean declaring whether the user can select more than one file at a time.

EXTRA_LOCAL_ONLY

A boolean that declares whether the returned file must be available directly from the device, rather than requiring a download from a remote service.

Category (optional)

CATEGORY_OPENABLE

To return only "openable" files that can be represented as a file stream with openFileDescriptor().

Example intent to get a photo:

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
        ...
    }
}

Example intent filter to return a photo:

<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 OpenableColumns
             and ContentResolver.openFileDescriptor() -->
        <category android:name="android.intent.category.OPENABLE" />
    </intent-filter>
</activity>

Open a specific type of file

Instead of retrieving a copy of a file that you must import to your app (by using the ACTION_GET_CONTENTaction), when running on Android 4.4 or higher, you can instead request to open a file that's managed by another app by using the 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 ACTION_CREATE_DOCUMENT action instead. For example, instead of selecting from existing PDF documents, the 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.

Whereas the intent delivered to your onActivityResult() method from the ACTION_GET_CONTENT action may return a URI of any type, the result intent from ACTION_OPEN_DOCUMENT and ACTION_CREATE_DOCUMENT always specify the chosen file as a content: URI that's backed by a DocumentsProvider. You can open the file withopenFileDescriptor() and query its details using columns from DocumentsContract.Document.

The returned URI grants your app long-term read access to the file (also possibly with write access). So theACTION_OPEN_DOCUMENT action is particularly useful (instead of using 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.

You can also allow the user to select multiple files by adding EXTRA_ALLOW_MULTIPLE to the intent, set to true. If the user selects just one item, then you can retrieve the item from getData(). If the user selects more than one item, then getData() returns null and you must instead retrieve each item from a ClipData object that is returned by getClipData().

Note: Your intent must specify a MIME type and must declare the CATEGORY_OPENABLE category. If appropriate, you can specify more than one MIME type by adding an array of MIME types with theEXTRA_MIME_TYPES extra—if you do so, you must set the primary MIME type in setType() to "*/*".

Action

ACTION_OPEN_DOCUMENT or
ACTION_CREATE_DOCUMENT

Data URI Scheme

None

MIME Type

The MIME type corresponding to the file type the user should select.

Extras

EXTRA_MIME_TYPES

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  setType() to  "*/*".

EXTRA_ALLOW_MULTIPLE

A boolean that declares whether the user can select more than one file at a time.

EXTRA_TITLE

For use with  ACTION_CREATE_DOCUMENT to specify an initial file name.

EXTRA_LOCAL_ONLY

A boolean that declares whether the returned file must be available directly from the device, rather than requiring a download from a remote service.

Category

CATEGORY_OPENABLE

To return only "openable" files that can be represented as a file stream with openFileDescriptor().

Example intent to get a photo:

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
        ...
    }
}

Third party apps cannot actually respond to an intent with the ACTION_OPEN_DOCUMENT action. Instead, the system receives this intent and displays all the files available from various apps in a unified user interface.

To provide your app's files in this UI and allow other apps to open them, you must implement aDocumentsProvider and include an intent filter for PROVIDER_INTERFACE("android.content.action.DOCUMENTS_PROVIDER"). For example:

<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>

For more information about how to make the files managed by your app openable from other apps, read theStorage Access Framework guide.

Local Actions

Call a car

Google Now

• "get me a taxi"
• "call me a car"

(Android Wear only)

To call a taxi, use the ACTION_RESERVE_TAXI_RESERVATION action.

Note: Apps must ask for confirmation from the user before completing the action.

Action

ACTION_RESERVE_TAXI_RESERVATION

Data URI

None

MIME Type

None

Extras

None

Example intent:

public void callCar() {
    Intent intent = new Intent(ReserveIntents.ACTION_RESERVE_TAXI_RESERVATION);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

Example intent filter:

<activity ...>
    <intent-filter>
        <action android:name="com.google.android.gms.actions.RESERVE_TAXI_RESERVATION" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Maps

Show a location on a map

To open a map, use the ACTION_VIEW action and specify the location information in the intent data with one of the schemes defined below.

Action

ACTION_VIEW

Data URI Scheme

geo:latitude,longitude

Show the map at the given longitude and latitude.

Example: "geo:47.6,-122.3"

geo:latitude,longitude?z=zoom

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  lat, lng. The highest (closest) zoom level is 23.

Example: "geo:47.6,-122.3?z=11"

geo:0,0?q=lat,lng(label)

Show the map at the given longitude and latitude with a string label.

Example: "geo:0,0?q=34.99,-106.61(Treasure)"

geo:0,0?q=my+street+address

Show the location for "my street address" (may be a specific address or location query).

Example: "geo:0,0?q=1600+Amphitheatre+Parkway%2C+CA"

Note: All strings passed in the geo URI must be encoded. For example, the string 1st & Pike, Seattle should become 1st%20%26%20Pike%2C%20Seattle. Spaces in the string can be encoded with %20 or replaced with the plus sign (+).

MIME Type

None

Example intent:

public void showMap(Uri geoLocation) {
    Intent intent = new Intent(Intent.ACTION_VIEW);
    intent.setData(geoLocation);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

Example intent filter:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="geo" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Music or Video

Play a media file

To play a music file, use the ACTION_VIEW action and specify the URI location of the file in the intent data.

Action

ACTION_VIEW

Data URI Scheme

file:<URI>

content:<URI>

http:<URL>

MIME Type

"audio/*"

"application/ogg"

"application/x-ogg"

"application/itunes"

Or any other that your app may require.

Example intent:

public void playMedia(Uri file) {
    Intent intent = new Intent(Intent.ACTION_VIEW);
    intent.setData(file);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

Example intent filter:

<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>

Play music based on a search query

Google Now

• "play michael jackson billie jean"

To play music based on a search query, use theINTENT_ACTION_MEDIA_PLAY_FROM_SEARCH intent. An app may fire this intent in response to the user's voice command to play music. The receiving app for this intent performs a search within its inventory to match existing content to the given query and starts playing that content.

This intent should include the EXTRA_MEDIA_FOCUS string extra, which specifies the inteded search mode. For example, the search mode can specify whether the search is for an artist name or song name.

Action

INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH

Data URI Scheme

None

MIME Type

None

Extras

MediaStore.EXTRA_MEDIA_FOCUS (required)

Indicates the search mode (whether the user is looking for a particular artist, album, song, or playlist). Most search modes take additional extras. For example, if the user is interested in listening to a particular song, the intent might have three additional extras: the song title, the artist, and the album. This intent supports the following search modes for each value ofEXTRA_MEDIA_FOCUS:

Any - "vnd.android.cursor.item/*"

Play any music. The receiving app should play some music based on a smart choice, such as the last playlist the user listened to.

Additional extras:

• QUERY (required) - An empty string. This extra is always provided for backward compatibility: existing apps that do not know about search modes can process this intent as an unstructured search.

Unstructured - "vnd.android.cursor.item/*"

Play a particular song, album or genre from an unstructured search query. Apps may generate an intent with this search mode when they can't identify the type of content the user wants to listen to. Apps should use more specific search modes when possible.

Additional extras:

• QUERY (required) - A string that contains any combination of: the artist, the album, the song name, or the genre.

Genre - Audio.Genres.ENTRY_CONTENT_TYPE

Play music of a particular genre.

Additional extras:

• "android.intent.extra.genre" (required) - The genre.
• QUERY (required) - The genre. This extra is always provided for backward compatibility: existing apps that do not know about search modes can process this intent as an unstructured search.

Artist - Audio.Artists.ENTRY_CONTENT_TYPE

Play music from a particular artist.

Additional extras:

• EXTRA_MEDIA_ARTIST (required) - The artist.
• "android.intent.extra.genre" - The genre.
• QUERY (required) - A string that contains any combination of the artist or the genre. This extra is always provided for backward compatibility: existing apps that do not know about search modes can process this intent as an unstructured search.

Album - Audio.Albums.ENTRY_CONTENT_TYPE

Play music from a particular album.

Additional extras:

• EXTRA_MEDIA_ALBUM (required) - The album.
• EXTRA_MEDIA_ARTIST - The artist.
• "android.intent.extra.genre" - The genre.
• QUERY (required) - A string that contains any combination of the album or the artist. This extra is always provided for backward compatibility: existing apps that do not know about search modes can process this intent as an unstructured search.

Song - "vnd.android.cursor.item/audio"

Play a particular song.

Additional extras:

• EXTRA_MEDIA_ALBUM - The album.
• EXTRA_MEDIA_ARTIST - The artist.
• "android.intent.extra.genre" - The genre.
• EXTRA_MEDIA_TITLE (required) - The song name.
• QUERY (required) - A string that contains any combination of: the album, the artist, the genre, or the title. This extra is always provided for backward compatibility: existing apps that do not know about search modes can process this intent as an unstructured search.

Playlist - Audio.Playlists.ENTRY_CONTENT_TYPE

Play a particular playlist or a playlist that matches some criteria specified by additional extras.

Additional extras:

• EXTRA_MEDIA_ALBUM - The album.
• EXTRA_MEDIA_ARTIST - The artist.
• "android.intent.extra.genre" - The genre.
• "android.intent.extra.playlist" - The playlist.
• EXTRA_MEDIA_TITLE - The song name that the playlist is based on.
• QUERY (required) - A string that contains any combination of: the album, the artist, the genre, the playlist, or the title. This extra is always provided for backward compatibility: existing apps that do not know about search modes can process this intent as an unstructured search.

Example intent:

If the user wants to listen to music from a particular artist, a search app may generate the following intent:

public void playSearchArtist(String artist) {
    Intent intent = new Intent(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH);
    intent.putExtra(MediaStore.EXTRA_MEDIA_FOCUS,
                    MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE);
    intent.putExtra(MediaStore.EXTRA_MEDIA_ARTIST, artist);
    intent.putExtra(SearchManager.QUERY, artist);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

Example intent filter:

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.MEDIA_PLAY_FROM_SEARCH" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

When handling this intent, your activity should check the value of the EXTRA_MEDIA_FOCUS extra in the incomingIntent to determine the search mode. Once your activity has identified the search mode, it should read the values of the additional extras for that particular search mode. With this information your app can then perform the search within its inventory to play the content that matches the search query. For example:

protected void onCreate(Bundle savedInstanceState) {
    ...
    Intent intent = this.getIntent();
    if (intent.getAction().compareTo(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH) == 0) {

        String mediaFocus = intent.getStringExtra(MediaStore.EXTRA_MEDIA_FOCUS);
        String query = intent.getStringExtra(SearchManager.QUERY);

        // Some of these extras may not be available depending on the search mode
        String album = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ALBUM);
        String artist = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ARTIST);
        String genre = intent.getStringExtra("android.intent.extra.genre");
        String playlist = intent.getStringExtra("android.intent.extra.playlist");
        String title = intent.getStringExtra(MediaStore.EXTRA_MEDIA_TITLE);

        // Determine the search mode and use the corresponding extras
        if (mediaFocus == null) {
            // 'Unstructured' search mode (backward compatible)
            playUnstructuredSearch(query);

        } else if (mediaFocus.compareTo("vnd.android.cursor.item/*") == 0) {
            if (query.isEmpty()) {
                // 'Any' search mode
                playResumeLastPlaylist();
            } else {
                // 'Unstructured' search mode
                playUnstructuredSearch(query);
            }

        } else if (mediaFocus.compareTo(MediaStore.Audio.Genres.ENTRY_CONTENT_TYPE) == 0) {
            // 'Genre' search mode
            playGenre(genre);

        } else if (mediaFocus.compareTo(MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE) == 0) {
            // 'Artist' search mode
            playArtist(artist, genre);

        } else if (mediaFocus.compareTo(MediaStore.Audio.Albums.ENTRY_CONTENT_TYPE) == 0) {
            // 'Album' search mode
            playAlbum(album, artist);

        } else if (mediaFocus.compareTo("vnd.android.cursor.item/audio") == 0) {
            // 'Song' search mode
            playSong(album, artist, genre, title);

        } else if (mediaFocus.compareTo(MediaStore.Audio.Playlists.ENTRY_CONTENT_TYPE) == 0) {
            // 'Playlist' search mode
            playPlaylist(album, artist, genre, playlist, title);
        }
    }
}

Phone

Initiate a phone call

To open the phone app and dial a phone number, use the 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 Call button to begin the phone call.

Google Now

• "call 555-5555"
• "call bob"
• "call voicemail"

To place a phone call directly, use the ACTION_CALL action and specify a phone number using the URI scheme defined below. When the phone app opens, it begins the phone call; the user does not need to press theCall button.

The ACTION_CALL action requires that you add the CALL_PHONEpermission to your manifest file:

<uses-permission android:name="android.permission.CALL_PHONE" />

Action

• ACTION_DIAL - Opens the dialer or phone app.
• ACTION_CALL - Places a phone call (requires the CALL_PHONE permission)

Data URI Scheme

• tel:<phone-number>
• voicemail:<phone-number>

MIME Type

None

Valid telephone numbers are those defined in the IETF RFC 3966. Valid examples include the following:

• tel:2125551212
• tel:(212) 555 1212

The Phone's dialer is good at normalizing schemes, such as telephone numbers. So the scheme described isn't strictly required in the Uri.parse() method. However, if you have not tried a scheme or are unsure whether it can be handled, use the Uri.fromParts() method instead.

Example intent:

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);
    }
}

Search

Search using a specific app

Google Now

• "search for cat videos on myvideoapp"

VIDEO

Voice search in your app

To support search within the context of your app, declare an intent filter in your app with the SEARCH_ACTION action, as shown in the example intent filter below.

Action

"com.google.android.gms.actions.SEARCH_ACTION"

Support search queries from Google Now.

Extras

QUERY

A string that contains the search query.

Example intent filter:

<activity android:name=".SearchActivity">
    <intent-filter>
        <action android:name="com.google.android.gms.actions.SEARCH_ACTION"/>
        <category android:name="android.intent.category.DEFAULT"/>
    </intent-filter>
</activity>

Perform a web search

To initiate a web search, use the ACTION_WEB_SEARCH action and specify the search string in theSearchManager.QUERY extra.

Action

ACTION_WEB_SEARCH

Data URI Scheme

None

MIME Type

None

Extras

SearchManager.QUERY

The search string.

Example intent:

public void searchWeb(String query) {
    Intent intent = new Intent(Intent.ACTION_SEARCH);
    intent.putExtra(SearchManager.QUERY, query);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

Settings

Open a specific section of Settings

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.

Action

ACTION_SETTINGS
ACTION_WIRELESS_SETTINGS
ACTION_AIRPLANE_MODE_SETTINGS
ACTION_WIFI_SETTINGS
ACTION_APN_SETTINGS
ACTION_BLUETOOTH_SETTINGS
ACTION_DATE_SETTINGS
ACTION_LOCALE_SETTINGS
ACTION_INPUT_METHOD_SETTINGS
ACTION_DISPLAY_SETTINGS
ACTION_SECURITY_SETTINGS
ACTION_LOCATION_SOURCE_SETTINGS
ACTION_INTERNAL_STORAGE_SETTINGS
ACTION_MEMORY_CARD_SETTINGS

See the Settings documentation for additional settings screens that are available.

Data URI Scheme

None

MIME Type

None

Example intent:

public void openWifiSettings() {
    Intent intent = new Intent(Intent.ACTION_WIFI_SETTINGS);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

Text Messaging

Compose an SMS/MMS message with attachment

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.

Action

ACTION_SENDTO or
ACTION_SEND or
ACTION_SEND_MULTIPLE

Data URI Scheme

sms:<phone_number>

smsto:<phone_number>

mms:<phone_number>

mmsto:<phone_number>

Each of these schemes are handled the same.

MIME Type

"text/plain"

"image/*"

"video/*"

Extras

"subject"

A string for the message subject (usually for MMS only).

"sms_body"

A string for the text message.

EXTRA_STREAM

A  Uri pointing to the image or video to attach. If using the  ACTION_SEND_MULTIPLE action, this extra should be an  ArrayList of  Uris pointing to the images/videos to attach.

Example intent:

public void composeMmsMessage(String message, Uri attachment) {
    Intent intent = new Intent(Intent.ACTION_SENDTO);
    intent.setType(HTTP.PLAIN_TEXT_TYPE);
    intent.putExtra("sms_body", message);
    intent.putExtra(Intent.EXTRA_STREAM, attachment);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

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 ACTION_SENDTO action and include the "smsto:" data scheme. For example:

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);
    }
}

Example intent filter:

<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>

Note: 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 default SMS app on Android 4.4 and higher. For more information, see the documentation at Telephony.

Web Browser

Load a web URL

Google Now

• "open example.com"

To open a web page, use the ACTION_VIEW action and specify the web URL in the intent data.

Action

ACTION_VIEW

Data URI Scheme

http:<URL>
https:<URL>

MIME Type

"text/plain"

"text/html"

"application/xhtml+xml"

"application/vnd.wap.xhtml+xml"

Example intent:

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);
    }
}

Example intent filter:

<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>

Tip: 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.

Verify Intents with the Android Debug Bridge

To verify that your app responds to the intents that you want to support, you can use the adb tool to fire specific intents:

1. Set up an Android device for development, or use a virtual device.
2. Install a version of your app that handles the intents you want to support.
3. Fire an intent using adb:

   adb shell am start -a <ACTION> -t <MIME_TYPE> -d <DATA> \
     -e <EXTRA_NAME> <EXTRA_VALUE> -n <ACTIVITY>
   

   For example:

   adb shell am start -a android.intent.action.DIAL \
     -d tel:555-5555 -n org.example.MyApp/.MyActivity
   

4. If you defined the required intent filters, your app should handle the intent.

For more information, see ADB Shell Commands.

Intents Fired by Google Now

Google Now recognizes many voice commands and fires intents for them. As such, users may launch your app with a Google Now voice command if your app declares the corresponding intent filter. For example, if your app can set an alarm and you add the corresponding intent filter to your manifest file, Google Now lets users choose your app when they request to set an alarm, as shown in figure 1.

Figure 1. Google Now lets users choose from installed apps that support a given action.

Google Now recognizes voice commands for the actions listed in table 1. For more information about declaring each intent filter, click on the action description.

Table 1. Voice commands recognized by Google Now (Google Search app v3.6).

Category	Details and Examples	Action Name
Alarm	Set alarm "set an alarm for 7 am"	AlarmClock.ACTION_SET_ALARM
	Set timer "set a timer for 5 minutes"	AlarmClock.ACTION_SET_TIMER
Communication	Call a number "call 555-5555" "call bob" "call voicemail"	Intent.ACTION_CALL
Local	Book a car "call me a car" "book me a taxi"	ReserveIntents .ACTION_RESERVE_TAXI_RESERVATION
Media	Play music from search "play michael jackson billie jean"	MediaStore .INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH
	Take a picture "take a picture"	MediaStore .INTENT_ACTION_STILL_IMAGE_CAMERA
	Record a video "record a video"	MediaStore .INTENT_ACTION_VIDEO_CAMERA
Search	Search using a specific app "search for cat videos  on myvideoapp"	"com.google.android.gms.actions .SEARCH_ACTION"
Web browser	Open URL "open example.com"	Intent.ACTION_VIEW

Get news & tips 

Blog  Support