Contacts
class Contacts : BaseColumns, ContactsContract.ContactsColumns, ContactsContract.ContactOptionsColumns, ContactsContract.ContactNameColumns, ContactsContract.ContactStatusColumns
kotlin.Any | |
↳ | android.provider.ContactsContract.Contacts |
Constants for the contacts table, which contains a record per aggregate of raw contacts representing the same person.
Operations
- Insert
- A Contact cannot be created explicitly. When a raw contact is inserted, the provider will first try to find a Contact representing the same person. If one is found, the raw contact's
RawContacts#CONTACT_ID
column gets the _ID of the aggregate Contact. If no match is found, the provider automatically inserts a new Contact and puts its _ID into theRawContacts#CONTACT_ID
column of the newly inserted raw contact. - Update
- Only certain columns of Contact are modifiable:
STARRED
,CUSTOM_RINGTONE
,SEND_TO_VOICEMAIL
. Changing any of these columns on the Contact also changes them on all constituent raw contacts. - Delete
- Be careful with deleting Contacts! Deleting an aggregate contact deletes all constituent raw contacts. The corresponding sync adapters will notice the deletions of their respective raw contacts and remove them from their back end storage.
- Query
-
- If you need to read an individual contact, consider using
CONTENT_LOOKUP_URI
instead ofCONTENT_URI
. - If you need to look up a contact by the phone number, use
PhoneLookup.CONTENT_FILTER_URI
, which is optimized for this purpose. - If you need to look up a contact by partial name, e.g. to produce filter-as-you-type suggestions, use the
CONTENT_FILTER_URI
URI. - If you need to look up a contact by some data element like email address, nickname, etc, use a query against the
ContactsContract.Data
table. The result will contain contact ID, name etc.
- If you need to read an individual contact, consider using
Columns
Contacts | |||
---|---|---|---|
long | _ID |
read-only | Row ID. Consider using LOOKUP_KEY instead. |
String | LOOKUP_KEY |
read-only | An opaque value that contains hints on how to find the contact if its row id changed as a result of a sync or aggregation. |
long | NAME_RAW_CONTACT_ID | read-only | The ID of the raw contact that contributes the display name to the aggregate contact. During aggregation one of the constituent raw contacts is chosen using a heuristic: a longer name or a name with more diacritic marks or more upper case characters is chosen. |
String | DISPLAY_NAME_PRIMARY | read-only | The display name for the contact. It is the display name contributed by the raw contact referred to by the NAME_RAW_CONTACT_ID column. |
long | PHOTO_ID |
read-only | Reference to the row in the ContactsContract.Data table holding the photo. That row has the mime type CommonDataKinds.Photo#CONTENT_ITEM_TYPE . The value of this field is computed automatically based on the CommonDataKinds.Photo#IS_SUPER_PRIMARY field of the data rows of that mime type. |
long | PHOTO_URI |
read-only | A URI that can be used to retrieve the contact's full-size photo. This column is the preferred method of retrieving the contact photo. |
long | PHOTO_THUMBNAIL_URI |
read-only | A URI that can be used to retrieve the thumbnail of contact's photo. This column is the preferred method of retrieving the contact photo. |
int | IN_VISIBLE_GROUP |
read-only | An indicator of whether this contact is supposed to be visible in the UI. "1" if the contact has at least one raw contact that belongs to a visible group; "0" otherwise. |
int | HAS_PHONE_NUMBER |
read-only | An indicator of whether this contact has at least one phone number. "1" if there is at least one phone number, "0" otherwise. |
int | STARRED |
read/write | An indicator for favorite contacts: '1' if favorite, '0' otherwise. When raw contacts are aggregated, this field is automatically computed: if any constituent raw contacts are starred, then this field is set to '1'. Setting this field automatically changes the corresponding field on all constituent raw contacts. |
String | CUSTOM_RINGTONE |
read/write | A custom ringtone associated with a contact. Typically this is the URI returned by an activity launched with the android.media.RingtoneManager#ACTION_RINGTONE_PICKER intent. |
int | SEND_TO_VOICEMAIL |
read/write | An indicator of whether calls from this contact should be forwarded directly to voice mail ('1') or not ('0'). When raw contacts are aggregated, this field is automatically computed: if all constituent raw contacts have SEND_TO_VOICEMAIL=1, then this field is set to '1'. Setting this field automatically changes the corresponding field on all constituent raw contacts. |
int | CONTACT_PRESENCE |
read-only | Contact IM presence status. See StatusUpdates for individual status definitions. Automatically computed as the highest presence of all constituent raw contacts. The provider may choose not to store this value in persistent storage. The expectation is that presence status will be updated on a regular basis. |
String | CONTACT_STATUS |
read-only | Contact's latest status update. Automatically computed as the latest of all constituent raw contacts' status updates. |
long | CONTACT_STATUS_TIMESTAMP |
read-only | The absolute time in milliseconds when the latest status was inserted/updated. |
String | CONTACT_STATUS_RES_PACKAGE |
read-only | The package containing resources for this status: label and icon. |
long | CONTACT_STATUS_LABEL |
read-only | The resource ID of the label describing the source of contact status, e.g. "Google Talk". This resource is scoped by the CONTACT_STATUS_RES_PACKAGE . |
long | CONTACT_STATUS_ICON |
read-only | The resource ID of the icon for the source of contact status. This resource is scoped by the CONTACT_STATUS_RES_PACKAGE . |
Summary
Nested classes | |
---|---|
A read-only sub-directory of a single contact aggregate that contains all aggregation suggestions (other contacts). |
|
A sub-directory of a single contact that contains all of the constituent raw contact |
|
A sub-directory of a contact that contains all of its |
|
A read-only sub-directory of a single contact that contains the contact's primary photo. |
Constants | |
---|---|
static String |
The MIME type of a |
static String |
The MIME type of |
static String |
The MIME type of a |
static String |
Add this query parameter to a URI to get back row counts grouped by the address book index as cursor extras. |
static String |
The array of group counts for the corresponding group. |
static String |
The array of address book index titles, which are returned in the same order as the data in the cursor. |
static String |
Boolean parameter that may be used with |
Inherited constants | |
---|---|
Public methods | |
---|---|
open static Uri! |
getLookupUri(resolver: ContentResolver!, contactUri: Uri!) Builds a |
open static Uri! |
getLookupUri(contactId: Long, lookupKey: String!) Build a |
open static Boolean |
isEnterpriseContactId(contactId: Long) Return |
open static Uri! |
lookupContact(resolver: ContentResolver!, lookupUri: Uri!) Computes a content URI (see |
open static Unit |
markAsContacted(resolver: ContentResolver!, contactId: Long) Mark a contact as having been contacted. |
open static InputStream! |
openContactPhotoInputStream(cr: ContentResolver!, contactUri: Uri!, preferHighres: Boolean) Opens an InputStream for the contacts's photo and returns the photo as a byte stream. |
open static InputStream! |
openContactPhotoInputStream(cr: ContentResolver!, contactUri: Uri!) Opens an InputStream for the contacts's thumbnail photo and returns the photo as a byte stream. |
Properties | |
---|---|
static Uri! |
The content:// style URI used for "type-to-filter" functionality on the |
static Uri! |
The content:// style URI for showing a list of frequently contacted people. |
static Uri! | |
static Uri! |
A content:// style URI for this table that should be used to create shortcuts or otherwise create long-term links to contacts. |
static Uri! |
Base |
static Uri! |
The content:// style URI used for "type-to-filter" functionality on the |
static Uri! |
The content:// style URI for this table joined with useful data from |
static Uri! |
The content:// style URI for this table |
static Uri! |
Base |
static Uri! |
It supports the similar semantics as |
static Uri |
URI used for getting all contacts from both the calling user and the managed profile that is linked to it. |
Constants
CONTENT_ITEM_TYPE
static val CONTENT_ITEM_TYPE: String
The MIME type of a CONTENT_URI
subdirectory of a single person.
Value: "vnd.android.cursor.item/contact"
CONTENT_TYPE
static val CONTENT_TYPE: String
The MIME type of CONTENT_URI
providing a directory of people.
Value: "vnd.android.cursor.dir/contact"
CONTENT_VCARD_TYPE
static val CONTENT_VCARD_TYPE: String
The MIME type of a CONTENT_URI
subdirectory of a single person.
Value: "text/x-vcard"
EXTRA_ADDRESS_BOOK_INDEX
static val EXTRA_ADDRESS_BOOK_INDEX: String
Add this query parameter to a URI to get back row counts grouped by the address book index as cursor extras. For most languages it is the first letter of the sort key. This parameter does not affect the main content of the cursor.
Example: import android.provider.ContactsContract.Contacts; Uri uri = Contacts.CONTENT_URI.buildUpon() .appendQueryParameter(Contacts.EXTRA_ADDRESS_BOOK_INDEX, "true") .build(); Cursor cursor = getContentResolver().query(uri, new String[] {Contacts.DISPLAY_NAME}, null, null, null); Bundle bundle = cursor.getExtras(); if (bundle.containsKey(Contacts.EXTRA_ADDRESS_BOOK_INDEX_TITLES) && bundle.containsKey(Contacts.EXTRA_ADDRESS_BOOK_INDEX_COUNTS)) { String sections[] = bundle.getStringArray(Contacts.EXTRA_ADDRESS_BOOK_INDEX_TITLES); int counts[] = bundle.getIntArray(Contacts.EXTRA_ADDRESS_BOOK_INDEX_COUNTS); }
Value: "android.provider.extra.ADDRESS_BOOK_INDEX"
EXTRA_ADDRESS_BOOK_INDEX_COUNTS
static val EXTRA_ADDRESS_BOOK_INDEX_COUNTS: String
The array of group counts for the corresponding group. Contains the same number of elements as the EXTRA_ADDRESS_BOOK_INDEX_TITLES array.
TYPE: int[]
Value: "android.provider.extra.ADDRESS_BOOK_INDEX_COUNTS"
EXTRA_ADDRESS_BOOK_INDEX_TITLES
static val EXTRA_ADDRESS_BOOK_INDEX_TITLES: String
The array of address book index titles, which are returned in the same order as the data in the cursor.
TYPE: String[]
Value: "android.provider.extra.ADDRESS_BOOK_INDEX_TITLES"
QUERY_PARAMETER_VCARD_NO_PHOTO
static val QUERY_PARAMETER_VCARD_NO_PHOTO: String
Boolean parameter that may be used with CONTENT_VCARD_URI
and CONTENT_MULTI_VCARD_URI
to indicate that the returned vcard should not contain a photo. This is useful for obtaining a space efficient vcard.
Value: "no_photo"
Public methods
getLookupUri
open static fun getLookupUri(
resolver: ContentResolver!,
contactUri: Uri!
): Uri!
Builds a CONTENT_LOOKUP_URI
style Uri
describing the requested Contacts
entry.
Parameters | |
---|---|
contactUri |
Uri!: A CONTENT_URI row, or an existing CONTENT_LOOKUP_URI to attempt refreshing. |
getLookupUri
open static fun getLookupUri(
contactId: Long,
lookupKey: String!
): Uri!
Build a CONTENT_LOOKUP_URI
lookup Uri
using the given ContactsContract.Contacts#_ID
and LOOKUP_KEY
.
Returns null if unable to construct a valid lookup URI from the provided parameters.
isEnterpriseContactId
open static fun isEnterpriseContactId(contactId: Long): Boolean
Return true
if a contact ID is from the contacts provider on the managed profile. PhoneLookup#ENTERPRISE_CONTENT_FILTER_URI
and similar APIs may return such IDs.
lookupContact
open static fun lookupContact(
resolver: ContentResolver!,
lookupUri: Uri!
): Uri!
Computes a content URI (see CONTENT_URI
) given a lookup URI.
Returns null if the contact cannot be found.
markAsContacted
open static funmarkAsContacted(
resolver: ContentResolver!,
contactId: Long
): Unit
Deprecated: Contacts affinity information is no longer supported as of Android version android.os.Build.VERSION_CODES#Q
. This method is no-op.
Mark a contact as having been contacted. Updates two fields: TIMES_CONTACTED
and LAST_TIME_CONTACTED
. The TIMES_CONTACTED field is incremented by 1 and the LAST_TIME_CONTACTED field is populated with the current system time.
Caution: If you publish your app to the Google Play Store, this field is obsolete, regardless of Android version. For more information, see the Contacts Provider page.
Parameters | |
---|---|
resolver |
ContentResolver!: the ContentResolver to use |
contactId |
Long: the person who was contacted |
openContactPhotoInputStream
open static fun openContactPhotoInputStream(
cr: ContentResolver!,
contactUri: Uri!,
preferHighres: Boolean
): InputStream!
Opens an InputStream for the contacts's photo and returns the photo as a byte stream.
Parameters | |
---|---|
cr |
ContentResolver!: The content resolver to use for querying |
contactUri |
Uri!: the contact whose photo should be used. This can be used with either a CONTENT_URI or a CONTENT_LOOKUP_URI URI. |
preferHighres |
Boolean: If this is true and the contact has a higher resolution photo available, it is returned. If false, this function always tries to get the thumbnail |
Return | |
---|---|
InputStream! |
an InputStream of the photo, or null if no photo is present |
openContactPhotoInputStream
open static fun openContactPhotoInputStream(
cr: ContentResolver!,
contactUri: Uri!
): InputStream!
Opens an InputStream for the contacts's thumbnail photo and returns the photo as a byte stream.
Parameters | |
---|---|
cr |
ContentResolver!: The content resolver to use for querying |
contactUri |
Uri!: the contact whose photo should be used. This can be used with either a CONTENT_URI or a CONTENT_LOOKUP_URI URI. |
Return | |
---|---|
InputStream! |
an InputStream of the photo, or null if no photo is present |
Properties
CONTENT_FILTER_URI
static val CONTENT_FILTER_URI: Uri!
The content:// style URI used for "type-to-filter" functionality on the CONTENT_URI
URI. The filter string will be used to match various parts of the contact name. The filter argument should be passed as an additional path segment after this URI.
CONTENT_FREQUENT_URI
static valCONTENT_FREQUENT_URI: Uri!
Deprecated: Frequent contacts are no longer supported as of Android version Caution: If you publish your app to the Google Play Store, this field doesn't sort results based on contacts frequency. For more information, see the Contacts Provider page.android.os.Build.VERSION_CODES#Q
. This URI always returns an empty cursor.
The content:// style URI for showing a list of frequently contacted people.
CONTENT_LOOKUP_URI
static val CONTENT_LOOKUP_URI: Uri!
A content:// style URI for this table that should be used to create shortcuts or otherwise create long-term links to contacts. This URI should always be followed by a "/" and the contact's LOOKUP_KEY
. It can optionally also have a "/" and last known contact ID appended after that. This "complete" format is an important optimization and is highly recommended.
As long as the contact's row ID remains the same, this URI is equivalent to CONTENT_URI
. If the contact's row ID changes as a result of a sync or aggregation, this URI will look up the contact using indirect information (sync IDs or constituent raw contacts).
Lookup key should be appended unencoded - it is stored in the encoded form, ready for use in a URI.
CONTENT_MULTI_VCARD_URI
static val CONTENT_MULTI_VCARD_URI: Uri!
Base Uri
for referencing multiple Contacts
entry, created by appending LOOKUP_KEY
using Uri#withAppendedPath(Uri, String)
. The lookup keys have to be joined with the colon (":") separator, and the resulting string encoded. Provides OpenableColumns
columns when queried, or returns the referenced contact formatted as a vCard when opened through ContentResolver#openAssetFileDescriptor(Uri, String)
.
Usage example:
- The following code snippet creates a multi-vcard URI that references all the contacts in a user's database.
-
public Uri getAllContactsVcardUri() { Cursor cursor = getActivity().getContentResolver().query(Contacts.CONTENT_URI, new String[] {Contacts.LOOKUP_KEY}, null, null, null); if (cursor == null) { return null; } try { StringBuilder uriListBuilder = new StringBuilder(); int index = 0; while (cursor.moveToNext()) { if (index != 0) uriListBuilder.append(':'); uriListBuilder.append(cursor.getString(0)); index++; } return Uri.withAppendedPath(Contacts.CONTENT_MULTI_VCARD_URI, Uri.encode(uriListBuilder.toString())); } finally { cursor.close(); } }
CONTENT_STREQUENT_FILTER_URI
static val CONTENT_STREQUENT_FILTER_URI: Uri!
The content:// style URI used for "type-to-filter" functionality on the CONTENT_STREQUENT_URI
URI. The filter string will be used to match various parts of the contact name. The filter argument should be passed as an additional path segment after this URI.
Caution: If you publish your app to the Google Play Store, this field doesn't sort results based on contacts frequency. For more information, see the Contacts Provider page.
CONTENT_STREQUENT_URI
static val CONTENT_STREQUENT_URI: Uri!
The content:// style URI for this table joined with useful data from ContactsContract.Data
, filtered to include only starred contacts. Frequent contacts are no longer included in the result as of Android version android.os.Build.VERSION_CODES#Q
.
Caution: If you publish your app to the Google Play Store, this field doesn't sort results based on contacts frequency. For more information, see the Contacts Provider page.
CONTENT_URI
static val CONTENT_URI: Uri!
The content:// style URI for this table
CONTENT_VCARD_URI
static val CONTENT_VCARD_URI: Uri!
Base Uri
for referencing a single Contacts
entry, created by appending LOOKUP_KEY
using Uri#withAppendedPath(Uri, String)
. Provides OpenableColumns
columns when queried, or returns the referenced contact formatted as a vCard when opened through ContentResolver#openAssetFileDescriptor(Uri, String)
.
ENTERPRISE_CONTENT_FILTER_URI
static val ENTERPRISE_CONTENT_FILTER_URI: Uri!
It supports the similar semantics as CONTENT_FILTER_URI
and returns the same columns. This URI requires ContactsContract#DIRECTORY_PARAM_KEY
in parameters, otherwise it will throw IllegalArgumentException. The passed directory can belong either to the calling user or to a managed profile that is linked to it.
ENTERPRISE_CONTENT_URI
static val ENTERPRISE_CONTENT_URI: Uri
URI used for getting all contacts from both the calling user and the managed profile that is linked to it.
It supports the same semantics as CONTENT_URI
and returns the same columns.
If the calling user has no managed profile, it behaves in the exact same way as CONTENT_URI
.
If there is a managed profile linked to the calling user, it will return merged results from both.
Note: this query returns the calling user results before the managed profile results, and this order is not affected by the sorting parameter.
If a result is from the managed profile, the following changes are made to the data:
PHOTO_THUMBNAIL_URI
andPHOTO_URI
will be rewritten to special URIs. Use android.content.ContentResolver#openAssetFileDescriptor or its siblings to load pictures from them.PHOTO_ID
andPHOTO_FILE_ID
will be set to null. Don't use them._ID
andLOOKUP_KEY
will be replaced with artificial values. These values will be consistent across multiple queries, but do not use them in places that do not explicitly say they accept them. If they are used in theselection
param in android.content.ContentProvider#query, the result is undefined.- In order to tell whether a contact is from the managed profile, use
ContactsContract.Contacts#isEnterpriseContactId(long)
.