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 RawContacts table by the change of the ContactsContract.RawContactsColumns.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 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 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 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 ContentProviderOperation.Builder#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 ContactsContract.RawContactsColumns.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 ContactsContract#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 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

Constants

public static final int AGGREGATION_MODE_DEFAULT

public static final int AGGREGATION_MODE_DISABLED

public static final int AGGREGATION_MODE_IMMEDIATE

public static final int AGGREGATION_MODE_SUSPENDED

public static final String CONTENT_ITEM_TYPE

public static final String CONTENT_TYPE

Fields

public static final Uri CONTENT_URI

Public methods

public static Uri getContactLookupUri (ContentResolver resolver, 
                Uri rawContactUri)

public static String getLocalAccountName (Context context)

public static String getLocalAccountType (Context context)

public static EntityIterator newEntityIterator (Cursor cursor)