RawContacts

class RawContacts : 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 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 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

static val AGGREGATION_MODE_DEFAULT: Int

Value: 0

static val AGGREGATION_MODE_DISABLED: Int

Value: 3

static val AGGREGATION_MODE_IMMEDIATE: Int

Value: 1

static val AGGREGATION_MODE_SUSPENDED: Int

Value: 2

static val CONTENT_ITEM_TYPE: String

Value: "vnd.android.cursor.item/raw_contact"

static val CONTENT_TYPE: String

Value: "vnd.android.cursor.dir/raw_contact"

Public methods

static fun getContactLookupUri(
    resolver: ContentResolver!, 
    rawContactUri: Uri!
): Uri!

static fun getLocalAccountName(context: Context): String?

static fun getLocalAccountType(context: Context): String?

static fun newEntityIterator(cursor: Cursor!): EntityIterator!

Properties

static val CONTENT_URI: Uri!