java.lang.Object
   ↳ android.provider.ContactsContract.Contacts

Class Overview

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 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 the CONTACT_ID column of the newly inserted raw contact.
Update
Only certain columns of Contact are modifiable: TIMES_CONTACTED, LAST_TIME_CONTACTED, 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 of CONTENT_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.

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 CONTENT_ITEM_TYPE. The value of this field is computed automatically based on the IS_SUPER_PRIMARY field of the data rows of that mime type.
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 TIMES_CONTACTED read/write The number of times the contact has been contacted. See markAsContacted(ContentResolver, long). When raw contacts are aggregated, this field is computed automatically as the maximum number of times contacted among all constituent raw contacts. Setting this field automatically changes the corresponding field on all constituent raw contacts.
long LAST_TIME_CONTACTED read/write The timestamp of the last time the contact was contacted. See markAsContacted(ContentResolver, long). Setting this field also automatically increments TIMES_CONTACTED. When raw contacts are aggregated, this field is computed automatically as the latest time contacted of all constituent raw contacts. Setting this field automatically changes the corresponding field on all constituent raw contacts.
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 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 ContactsContract.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 basic.
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
class ContactsContract.Contacts.AggregationSuggestions

A read-only sub-directory of a single contact aggregate that contains all aggregation suggestions (other contacts). 
class ContactsContract.Contacts.Data A sub-directory of a single contact that contains all of the constituent raw contact ContactsContract.Data rows. 
class ContactsContract.Contacts.Photo A read-only sub-directory of a single contact that contains the contact's primary photo. 
Constants
Uri CONTENT_FILTER_URI The content:// style URI used for "type-to-filter" functionality on the CONTENT_URI URI.
Uri CONTENT_GROUP_URI
String CONTENT_ITEM_TYPE The MIME type of a CONTENT_URI subdirectory of a single person.
Uri CONTENT_LOOKUP_URI A content:// style URI for this table that should be used to create shortcuts or otherwise create long-term links to contacts.
Uri CONTENT_STREQUENT_FILTER_URI The content:// style URI used for "type-to-filter" functionality on the CONTENT_STREQUENT_URI URI.
Uri CONTENT_STREQUENT_URI The content:// style URI for this table joined with useful data from ContactsContract.Data, filtered to include only starred contacts and the most frequently contacted contacts.
String CONTENT_TYPE The MIME type of CONTENT_URI providing a directory of people.
Uri CONTENT_URI The content:// style URI for this table
String CONTENT_VCARD_TYPE The MIME type of a CONTENT_URI subdirectory of a single person.
Uri CONTENT_VCARD_URI Base Uri for referencing a single Contacts entry, created by appending LOOKUP_KEY using withAppendedPath(Uri, String).
String DISPLAY_NAME_ALTERNATIVE

An alternative representation of the display name, such as "family name first" instead of "given name first" for Western names.
String DISPLAY_NAME_PRIMARY

The standard text shown as the contact's display name, based on the best available information for the contact (for example, it might be the email address if the name is not available).
String DISPLAY_NAME_SOURCE The kind of data that is used as the display name for the contact, such as structured name or email address.
String PHONETIC_NAME

Pronunciation of the full name in the phonetic alphabet specified by PHONETIC_NAME_STYLE.
String PHONETIC_NAME_STYLE The phonetic alphabet used to represent the PHONETIC_NAME.
String SORT_KEY_ALTERNATIVE Sort key based on the alternative representation of the full name, DISPLAY_NAME_ALTERNATIVE.
String SORT_KEY_PRIMARY Sort key that takes into account locale-based traditions for sorting names in address books.
[Expand]
Inherited Constants
From interface android.provider.BaseColumns
From interface android.provider.ContactsContract.ContactOptionsColumns
From interface android.provider.ContactsContract.ContactStatusColumns
From interface android.provider.ContactsContract.ContactsColumns
Public Methods
static Uri getLookupUri(long contactId, String lookupKey)
Build a CONTENT_LOOKUP_URI lookup Uri using the given _ID and LOOKUP_KEY.
static Uri getLookupUri(ContentResolver resolver, Uri contactUri)
Builds a CONTENT_LOOKUP_URI style Uri describing the requested Contacts entry.
static Uri lookupContact(ContentResolver resolver, Uri lookupUri)
Computes a content URI (see CONTENT_URI) given a lookup URI.
static void markAsContacted(ContentResolver resolver, long contactId)
Mark a contact as having been contacted.
static InputStream openContactPhotoInputStream(ContentResolver cr, Uri contactUri)
Opens an InputStream for the contacts's default photo and returns the photo as a byte stream.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final Uri CONTENT_FILTER_URI

Since: API Level 5

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.

public static final Uri CONTENT_GROUP_URI

Since: API Level 5

public static final String CONTENT_ITEM_TYPE

Since: API Level 5

The MIME type of a CONTENT_URI subdirectory of a single person.

Constant Value: "vnd.android.cursor.item/contact"

public static final Uri CONTENT_LOOKUP_URI

Since: API Level 5

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.

public static final Uri CONTENT_STREQUENT_FILTER_URI

Since: API Level 5

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.

public static final Uri CONTENT_STREQUENT_URI

Since: API Level 5

The content:// style URI for this table joined with useful data from ContactsContract.Data, filtered to include only starred contacts and the most frequently contacted contacts.

public static final String CONTENT_TYPE

Since: API Level 5

The MIME type of CONTENT_URI providing a directory of people.

Constant Value: "vnd.android.cursor.dir/contact"

public static final Uri CONTENT_URI

Since: API Level 5

The content:// style URI for this table

public static final String CONTENT_VCARD_TYPE

Since: API Level 5

The MIME type of a CONTENT_URI subdirectory of a single person.

Constant Value: "text/x-vcard"

public static final Uri CONTENT_VCARD_URI

Since: API Level 5

Base Uri for referencing a single Contacts entry, created by appending LOOKUP_KEY using withAppendedPath(Uri, String). Provides OpenableColumns columns when queried, or returns the referenced contact formatted as a vCard when opened through openAssetFileDescriptor(Uri, String).

public static final String DISPLAY_NAME_ALTERNATIVE

Since: API Level

An alternative representation of the display name, such as "family name first" instead of "given name first" for Western names. If an alternative is not available, the values should be the same as DISPLAY_NAME_PRIMARY.

A contacts provider is free to provide alternatives as necessary for its target market. For example the default Android Open Source Project contacts provider currently provides an alternative in a single case: if the display name is based on the structured name and the structured name follows the Western full name style, then the field contains the "family name first" version of the full name. Other cases may be added later.

Constant Value: "display_name_alt"

public static final String DISPLAY_NAME_PRIMARY

Since: API Level

The standard text shown as the contact's display name, based on the best available information for the contact (for example, it might be the email address if the name is not available). The information actually used to compute the name is stored in DISPLAY_NAME_SOURCE.

A contacts provider is free to choose whatever representation makes most sense for its target market. For example in the default Android Open Source Project implementation, if the display name is based on the structured name and the structured name follows the Western full-name style, then this field contains the "given name first" version of the full name.

See Also
  • DISPLAY_NAME_ALTERNATIVE
Constant Value: "display_name"

public static final String DISPLAY_NAME_SOURCE

Since: API Level

The kind of data that is used as the display name for the contact, such as structured name or email address. See DisplayNameSources. TODO: convert DisplayNameSources to a link after it is un-hidden

Constant Value: "display_name_source"

public static final String PHONETIC_NAME

Since: API Level

Pronunciation of the full name in the phonetic alphabet specified by PHONETIC_NAME_STYLE.

The value may be set manually by the user. This capability is is of interest only in countries with commonly used phonetic alphabets, such as Japan and Korea. See PhoneticNameStyle.

TODO: convert PhoneticNameStyle to a link after it is un-hidden

Constant Value: "phonetic_name"

public static final String PHONETIC_NAME_STYLE

Since: API Level

The phonetic alphabet used to represent the PHONETIC_NAME. See PhoneticNameStyle. TODO: convert PhoneticNameStyle to a link after it is un-hidden

Constant Value: "phonetic_name_style"

public static final String SORT_KEY_ALTERNATIVE

Since: API Level

Sort key based on the alternative representation of the full name, DISPLAY_NAME_ALTERNATIVE. Thus for Western names, it is the one using the "family name first" format.

Constant Value: "sort_key_alt"

public static final String SORT_KEY_PRIMARY

Since: API Level

Sort key that takes into account locale-based traditions for sorting names in address books. The default sort key is DISPLAY_NAME_PRIMARY. For Chinese names the sort key is the name's Pinyin spelling, and for Japanese names it is the Hiragana version of the phonetic name.

Constant Value: "sort_key"

Public Methods

public static Uri getLookupUri (long contactId, String lookupKey)

Since: API Level 5

Build a CONTENT_LOOKUP_URI lookup Uri using the given _ID and LOOKUP_KEY.

public static Uri getLookupUri (ContentResolver resolver, Uri contactUri)

Since: API Level 5

Builds a CONTENT_LOOKUP_URI style Uri describing the requested Contacts entry.

Parameters
contactUri A CONTENT_URI row, or an existing CONTENT_LOOKUP_URI to attempt refreshing.

public static Uri lookupContact (ContentResolver resolver, Uri lookupUri)

Since: API Level 5

Computes a content URI (see CONTENT_URI) given a lookup URI.

Returns null if the contact cannot be found.

public static void markAsContacted (ContentResolver resolver, long contactId)

Since: API Level 5

Mark a contact as having been contacted. This updates the TIMES_CONTACTED and LAST_TIME_CONTACTED for the contact, plus the corresponding values of any associated raw contacts.

Parameters
resolver the ContentResolver to use
contactId the person who was contacted

public static InputStream openContactPhotoInputStream (ContentResolver cr, Uri contactUri)

Since: API Level 5

Opens an InputStream for the contacts's default photo and returns the photo as a byte stream. If there is not photo null will be returned.

Parameters
contactUri the contact whose photo should be used
Returns
  • an InputStream of the photo, or null if no photo is present