ContactsPickerSessionContract

class ContactsPickerSessionContract
kotlin.Any
   ↳ android.provider.ContactsPickerSessionContract

The contract between the Contacts Picker session provider and client applications. This contract defines the intent actions, extras, and URI structure used to interact with the Contacts Picker to select contacts and retrieve their data.

It allows apps to select one or more contacts without requiring android.Manifest.permission#READ_CONTACTS, enhancing user privacy and security. The client app receives one-time access to the user-selected contacts data.

Summary

Nested classes

Defines the contract for a Contacts Picker session, which represents the set of contacts selected by the user in a single picking operation.
Constants
static String

Intent action to launch the system Contacts Picker to select one or more contacts.
static String

The authority for the Contacts Picker session provider.
static String

A boolean extra that, when set to true, instructs the system Contacts Picker to only display contacts that possess data fields corresponding to *all* MIME type specified in EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS.
static String

A List<String> extra that specifies the types of contact data the client application is requesting.
static String

An integer extra that defines the maximum number of contacts a user can select in a single session.
Properties
static Uri

The base content:// style Uri for the Contacts Picker session provider.

Constants

ACTION_PICK_CONTACTS

static val ACTION_PICK_CONTACTS: String

Intent action to launch the system Contacts Picker to select one or more contacts. This action provides a modern way for applications to obtain contact information, differing from android.content.Intent#ACTION_PICK and android.content.Intent#ACTION_GET_CONTENT in several key ways:

  • It is specifically designed for picking contacts, offering a streamlined user experience.
  • The calling application gains one-time read access to the user-selected contact data, without requiring android.Manifest.permission#READ_CONTACTS.
  • Users benefit from a consistent UI to grant temporary access to their contact data.
  • Client applications can specify and receive multiple data fields (MIME types) corresponding to the selected contacts.

To use this intent, create an android.content.Intent with this action and launch it using android.app.Activity#startActivityForResult(android.content.Intent,int). The system Contacts Picker UI will be displayed, allowing the user to select one or more contacts. This contacts picker UI will:

  • Have eligible contacts displayed as a scrollable list to the user.
  • Enable users to select single/multiple contacts.
  • Enable users to search for contacts using display name.

The display and selection behavior can be customized using the following extras:

Upon successful contact(s) selection, the android.app.Activity#onActivityResult(int,int,android.content.Intent) callback will be invoked with android.app.Activity#RESULT_OK. The returned android.content.Intent will contain a session URI in its data field (see Session.CONTENT_URI), which should be used to query the selected contact data. For example: 

Uri sessionUri = data.getData();
      Cursor cursor = getContentResolver().query(sessionUri, projection, null, null, null);
      // Process cursor data

Starting from Android 17, this intent is handled by a system application by default. Third-party applications should not handle this intent as they will be ignored when the system attempts to resolve it.

Value: "android.provider.action.PICK_CONTACTS"

AUTHORITY

static val AUTHORITY: String

The authority for the Contacts Picker session provider. This string is used to construct content URIs for interacting with the Contacts Picker session data.

Value: "com.android.contacts.picker.sessions"

EXTRA_PICK_CONTACTS_MATCH_ALL_DATA_FIELDS

static val EXTRA_PICK_CONTACTS_MATCH_ALL_DATA_FIELDS: String

A boolean extra that, when set to true, instructs the system Contacts Picker to only display contacts that possess data fields corresponding to *all* MIME type specified in EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS.

If false (the default value), contacts will be displayed if they have data for *at least one* of the MIME types specified in EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS.

Value: "android.provider.extra.PICK_CONTACTS_MATCH_ALL_DATA_FIELDS"

EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS

static val EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS: String

A List<String> extra that specifies the types of contact data the client application is requesting. This extra serves two primary purposes:

  1. **Filtering:** Only contacts possessing data corresponding to at least one of the specified MIME types will be displayed in the Contacts Picker.
  2. **Data Return:** For selected contacts, only data corresponding to these specified MIME types will be returned to the calling application.
This extra must be populated with one or more of the following MIME types:

If EXTRA_PICK_CONTACTS_MATCH_ALL_DATA_FIELDS is set to true, only contacts having data corresponding to *all* of the MIME types specified in this extra will be displayed.

The Contacts Picker will throw an IllegalArgumentException if any of the MIME types provided in this extra are not among the allowed types listed above.

Clients are required to set this extra to ensure the picker can determine which information should be made available for selection. Example usage: 

List<String> requestedMimeTypes = new ArrayList<>();
      requestedMimeTypes.add(ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE);
      requestedMimeTypes.add(ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE);
      intent.putStringArrayListExtra(
              ContactsPickerSessionContract.EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS,
              (ArrayList<String>) requestedMimeTypes);
  
Value: "android.provider.extra.PICK_CONTACTS_REQUESTED_DATA_FIELDS"

EXTRA_PICK_CONTACTS_SELECTION_LIMIT

static val EXTRA_PICK_CONTACTS_SELECTION_LIMIT: String

An integer extra that defines the maximum number of contacts a user can select in a single session. The Contacts Picker uses this value to configure its UI.

If this extra is not set, the default selection limit is 50. The absolute maximum allowed value is 100.

Clients should not set this value higher than the documented maximum limit. The application handling ACTION_PICK_CONTACTS will throw an IllegalArgumentException if the provided value exceeds the maximum allowed limit.

Value: "android.provider.extra.PICK_CONTACTS_SELECTION_LIMIT"

Properties

AUTHORITY_URI

static val AUTHORITY_URI: Uri

The base content:// style Uri for the Contacts Picker session provider. All session-specific URIs are built upon this base URI.