ContactsContract.RawContacts

public static final class ContactsContract.RawContacts
extends Object implements BaseColumns, ContactsContract.RawContactsColumns, ContactsContract.ContactOptionsColumns, ContactsContract.ContactNameColumns, ContactsContract.SyncColumns

Constants for the raw contacts table, which contains one row of contact information for each person in each synced account. Sync adapters and contact management apps are the primary consumers of this API.

Aggregation

As soon as a raw contact is inserted or whenever its constituent data changes, the provider will check if the raw contact matches other existing raw contacts and if so will aggregate it with those. The aggregation is reflected in the ContactsContract.RawContacts table by the change of the CONTACT_ID field, which is the reference to the aggregate contact.

Changes to the structured name, organization, phone number, email address, or nickname trigger a re-aggregation.

See also ContactsContract.AggregationExceptions for a mechanism to control aggregation programmatically.

Operations

Insert

Raw contacts can be inserted incrementally or in a batch. The incremental method is more traditional but less efficient. It should be used only if no ContactsContract.RawContacts.Data values are available at the time the raw contact is created:

 ContentValues values = new ContentValues();
 values.put(RawContacts.ACCOUNT_TYPE, accountType);
 values.put(RawContacts.ACCOUNT_NAME, accountName);
 Uri rawContactUri = getContentResolver().insert(RawContacts.CONTENT_URI, values);
 long rawContactId = ContentUris.parseId(rawContactUri);
 

Once ContactsContract.RawContacts.Data values become available, insert those. For example, here's how you would insert a name:

 values.clear();
 values.put(Data.RAW_CONTACT_ID, rawContactId);
 values.put(Data.MIMETYPE, StructuredName.CONTENT_ITEM_TYPE);
 values.put(StructuredName.DISPLAY_NAME, "Mike Sullivan");
 getContentResolver().insert(Data.CONTENT_URI, values);
 

The batch method is by far preferred. It inserts the raw contact and its constituent data rows in a single database transaction and causes at most one aggregation pass.

 ArrayList<ContentProviderOperation> ops =
          new ArrayList<ContentProviderOperation>();
 ...
 int rawContactInsertIndex = ops.size();
 ops.add(ContentProviderOperation.newInsert(RawContacts.CONTENT_URI)
          .withValue(RawContacts.ACCOUNT_TYPE, accountType)
          .withValue(RawContacts.ACCOUNT_NAME, accountName)
          .build());

 ops.add(ContentProviderOperation.newInsert(Data.CONTENT_URI)
          .withValueBackReference(Data.RAW_CONTACT_ID, rawContactInsertIndex)
          .withValue(Data.MIMETYPE, StructuredName.CONTENT_ITEM_TYPE)
          .withValue(StructuredName.DISPLAY_NAME, "Mike Sullivan")
          .build());

 getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);
 

Note the use of withValueBackReference(String, int) to refer to the as-yet-unknown index value of the raw contact inserted in the first operation.

Update

Raw contacts can be updated incrementally or in a batch. Batch mode should be used whenever possible. The procedures and considerations are analogous to those documented above for inserts.

Delete

When a raw contact is deleted, all of its Data rows as well as StatusUpdates, AggregationExceptions, PhoneLookup rows are deleted automatically. When all raw contacts associated with a Contacts row are deleted, the Contacts row itself is also deleted automatically.

The invocation of resolver.delete(...), does not immediately delete a raw contacts row. Instead, it sets the DELETED flag on the raw contact and removes the raw contact from its aggregate contact. The sync adapter then deletes the raw contact from the server and finalizes phone-side deletion by calling resolver.delete(...) again and passing the CALLER_IS_SYNCADAPTER query parameter.

Some sync adapters are read-only, meaning that they only sync server-side changes to the phone, but not the reverse. If one of those raw contacts is marked for deletion, it will remain on the phone. However it will be effectively invisible, because it will not be part of any aggregate contact.

Query

It is easy to find all raw contacts in a Contact:

 Cursor c = getContentResolver().query(RawContacts.CONTENT_URI,
          new String[]{RawContacts._ID},
          RawContacts.CONTACT_ID + "=?",
          new String[]{String.valueOf(contactId)}, null);
 

To find raw contacts within a specific account, you can either put the account name and type in the selection or pass them as query parameters. The latter approach is preferable, especially when you can reuse the URI:

 Uri rawContactUri = RawContacts.CONTENT_URI.buildUpon()
          .appendQueryParameter(RawContacts.ACCOUNT_NAME, accountName)
          .appendQueryParameter(RawContacts.ACCOUNT_TYPE, accountType)
          .build();
 Cursor c1 = getContentResolver().query(rawContactUri,
          RawContacts.STARRED + "<>0", null, null, null);
 ...
 Cursor c2 = getContentResolver().query(rawContactUri,
          RawContacts.DELETED + "<>0", null, null, null);
 

The best way to read a raw contact along with all the data associated with it is by using the ContactsContract.RawContacts.Entity directory. If the raw contact has data rows, the Entity cursor will contain a row for each data row. If the raw contact has no data rows, the cursor will still contain one row with the raw contact-level information.

 Uri rawContactUri = ContentUris.withAppendedId(RawContacts.CONTENT_URI, rawContactId);
 Uri entityUri = Uri.withAppendedPath(rawContactUri, Entity.CONTENT_DIRECTORY);
 Cursor c = getContentResolver().query(entityUri,
          new String[]{RawContacts.SOURCE_ID, Entity.DATA_ID, Entity.MIMETYPE, Entity.DATA1},
          null, null, null);
 try {
     while (c.moveToNext()) {
         String sourceId = c.getString(0);
         if (!c.isNull(1)) {
             String mimeType = c.getString(2);
             String data = c.getString(3);
             ...
         }
     }
 } finally {
     c.close();
 }
 

Columns

Summary

Inherited constants
From interface android.provider.BaseColumns String _COUNT The count of rows in a directory. String _ID The unique ID for a row.
From interface android.provider.ContactsContract.RawContactsColumns String ACCOUNT_TYPE_AND_DATA_SET A concatenation of the account type and data set (delimited by a forward slash) - if the data set is empty, this will be the same as the account type. String AGGREGATION_MODE The aggregation mode for this contact. String BACKUP_ID Persistent unique id for each raw_contact within its account. String CONTACT_ID A reference to the _ID that this data belongs to. String DATA_SET The data set within the account that this row belongs to. String DELETED The "deleted" flag: "0" by default, "1" if the row has been marked for deletion. String METADATA_DIRTY Flag indicating that a raw contact's metadata has changed, and its metadata needs to be synchronized by the server. String RAW_CONTACT_IS_READ_ONLY The "read-only" flag: "0" by default, "1" if the row cannot be modified or deleted except by a sync adapter. String RAW_CONTACT_IS_USER_PROFILE Flag that reflects whether this raw contact belongs to the user's personal profile entry.
From interface android.provider.ContactsContract.ContactOptionsColumns String CUSTOM_RINGTONE URI for a custom ringtone associated with the contact. String LAST_TIME_CONTACTED The last time a contact was contacted. String PINNED The position at which the contact is pinned. String SEND_TO_VOICEMAIL Whether the contact should always be sent to voicemail. String STARRED Is the contact starred? Type: INTEGER (boolean) String TIMES_CONTACTED The number of times a contact has been contacted Type: INTEGER
From interface android.provider.ContactsContract.ContactNameColumns 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.
From interface android.provider.ContactsContract.SyncColumns String ACCOUNT_NAME The name of the account instance to which this row belongs, which when paired with ACCOUNT_TYPE identifies a specific account. String ACCOUNT_TYPE The type of account to which this row belongs, which when paired with ACCOUNT_NAME identifies a specific account. String DIRTY Flag indicating that VERSION has changed, and this row needs to be synchronized by its owning account. String SOURCE_ID String that uniquely identifies this row to its source account. String VERSION Version number that is updated whenever this row or its related data changes.
From interface android.provider.ContactsContract.BaseSyncColumns String SYNC1 Generic column for use by sync adapters. String SYNC2 Generic column for use by sync adapters. String SYNC3 Generic column for use by sync adapters. String SYNC4 Generic column for use by sync adapters.

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long millis, int nanos) Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed. final void wait(long millis) Causes the current thread to wait until either another thread invokes the notify() method or the notifyAll() method for this object, or a specified amount of time has elapsed. final void wait() Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object.

Constants

int AGGREGATION_MODE_DEFAULT

int AGGREGATION_MODE_DISABLED

int AGGREGATION_MODE_IMMEDIATE

int AGGREGATION_MODE_SUSPENDED

String CONTENT_ITEM_TYPE

String CONTENT_TYPE

Fields

Uri CONTENT_URI

Public methods

Uri getContactLookupUri (ContentResolver resolver, 
                Uri rawContactUri)

EntityIterator newEntityIterator (Cursor cursor)