Android insert contact intent

Common Intents

In this document show more show less

See also

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 Intent object. This type of intent is called an implicit intent because it does not specify the app component to start, but instead specifies an action and provides some data with which to perform the action.

When you call startActivity() or startActivityForResult() and pass it an implicit intent, the system resolves the intent to an app that can handle the intent and starts its corresponding 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.

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 intent filter to advertise your app’s ability to perform the same action.

Caution: If there are no apps on the device that can receive the implicit intent, your app will crash when it calls startActivity() . To first verify that an app exists to receive the intent, call resolveActivity() on your 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 startActivity() . If the result is null, you should not use the intent and, if possible, you should disable the feature that invokes the intent.

If you’re not familiar with how to create intents or intent filters, you should first read Intents and Intent Filters.

To learn how to fire the intents listed on this page from your development host, see Verify Intents with the Android Debug Bridge.

Google Now

Google Now fires some of the intents listed on this page in response to voice commands. For more information, see Intents Fired by Google Now.

Alarm Clock

Create an alarm

To create a new alarm, use the ACTION_SET_ALARM action and specify alarm details such as the time and message using extras defined below.

Note: Only the hour, minutes, and message extras are available in Android 2.3 (API level 9) and higher. The other extras were added in later versions of the platform.

Action ACTION_SET_ALARM Data URI None MIME Type None Extras EXTRA_HOUR The hour for the alarm. EXTRA_MINUTES The minutes for the alarm. EXTRA_MESSAGE A custom message to identify the alarm. EXTRA_DAYS An ArrayList including each week day on which this alarm should be repeated. Each day must be declared with an integer from the Calendar class such as MONDAY .

For a one-time alarm, do not specify this extra. EXTRA_RINGTONE A content: URI specifying a ringtone to use with the alarm, or VALUE_RINGTONE_SILENT for no ringtone.

To use the default ringtone, do not specify this extra. EXTRA_VIBRATE A boolean specifying whether to vibrate for this alarm. EXTRA_SKIP_UI A boolean specifying whether the responding app should skip its UI when setting the alarm. If true, the app should bypass any confirmation UI and simply set the specified alarm.

In order to invoke the ACTION_SET_ALARM intent, your app must have the SET_ALARM permission:

Example intent filter:

Create a timer

• «set timer for 5 minutes»

To create a countdown timer, use the ACTION_SET_TIMER action and specify timer details such as the duration using extras defined below.

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

Action ACTION_SET_TIMER Data URI None MIME Type None Extras EXTRA_LENGTH The length of the timer in seconds. EXTRA_MESSAGE A custom message to identify the timer. EXTRA_SKIP_UI A boolean specifying whether the responding app should skip its UI when setting the timer. If true, the app should bypass any confirmation UI and simply start the specified timer.

In order to invoke the ACTION_SET_TIMER intent, your app must have the SET_ALARM permission:

Example intent filter:

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

Example intent filter:

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 with Events.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 the CalendarContract.EventsColumns class.

Example intent filter:

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 or ACTION_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» .

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

Example intent filter:

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 Intent that includes a compressed thumbnail in an extra named «data» .

Start a camera app in still image mode

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

Example intent filter:

Start a camera app in video mode

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

Action INTENT_ACTION_VIDEO_CAMERA Data URI Scheme None MIME Type None Extras None

Example intent filter:

Contacts/People App

Select a contact

To have the user select a contact and provide your app access to all the contact information, use the ACTION_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.

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 the READ_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 the ContactsContract.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 .

View a contact

To display the details for a known contact, use the ACTION_VIEW action and specify the contact with a content: 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).

ActionACTION_VIEWData URI Scheme content: MIME Type None. The type is inferred from contact URI.

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 in ContactsContract.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).

ActionACTION_EDITData URI Scheme content: 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.

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 .

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.

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:

Example intent filter:

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 the 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).

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 adding EXTRA_ALLOW_MULTIPLE to the intent, set to true . You can then access each of the selected files in a ClipData object 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:

Example intent filter to return a photo:

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_CONTENT action), 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 with openFileDescriptor() 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 the ACTION_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 the EXTRA_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:

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 a DocumentsProvider and include an intent filter for PROVIDER_INTERFACE ( «android.content.action.DOCUMENTS_PROVIDER» ). For example:

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

Источник