java.lang.Object | |
↳ | android.provider.ContactsContract.RawContacts |
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.
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.
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.
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.
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.
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.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(); }
RawContacts | |||
---|---|---|---|
long | _ID |
read-only | Row ID. Sync adapters should try to preserve row IDs during updates. In other words, it is much better for a sync adapter to update a raw contact rather than to delete and re-insert it. |
long | CONTACT_ID |
read-only | The ID of the row in the ContactsContract.Contacts table
that this raw contact belongs
to. Raw contacts are linked to contacts by the aggregation process, which can be controlled
by the AGGREGATION_MODE field and ContactsContract.AggregationExceptions . |
int | AGGREGATION_MODE |
read/write | A mechanism that allows programmatic control of the aggregation process. The allowed
values are AGGREGATION_MODE_DEFAULT , AGGREGATION_MODE_DISABLED
and AGGREGATION_MODE_SUSPENDED . See also ContactsContract.AggregationExceptions . |
int | DELETED |
read/write | The "deleted" flag: "0" by default, "1" if the row has been marked
for deletion. When delete(Uri, String, String[]) is
called on a raw contact, it is marked for deletion and removed from its
aggregate contact. The sync adaptor deletes the raw contact on the server and
then calls ContactResolver.delete once more, this time passing the
CALLER_IS_SYNCADAPTER query parameter to finalize
the data removal. |
int | TIMES_CONTACTED |
read/write | The number of times the contact has been contacted. To have an effect
on the corresponding value of the aggregate contact, this field
should be set at the time the raw contact is inserted.
After that, this value is typically updated via
markAsContacted(ContentResolver, long) . |
long | LAST_TIME_CONTACTED |
read/write | The timestamp of the last time the contact was contacted. To have an effect
on the corresponding value of the aggregate contact, this field
should be set at the time the raw contact is inserted.
After that, this value is typically updated via
markAsContacted(ContentResolver, long) .
|
int | STARRED |
read/write | An indicator for favorite contacts: '1' if favorite, '0' otherwise. Changing this field immediately affects the corresponding aggregate contact: if any raw contacts in that aggregate contact are starred, then the contact itself is marked as starred. |
String | CUSTOM_RINGTONE |
read/write | A custom ringtone associated with a raw contact. Typically this is the
URI returned by an activity launched with the
ACTION_RINGTONE_PICKER intent.
To have an effect on the corresponding value of the aggregate contact, this field
should be set at the time the raw contact is inserted. To set a custom
ringtone on a contact, use the field Contacts.CUSTOM_RINGTONE
instead. |
int | SEND_TO_VOICEMAIL |
read/write | An indicator of whether calls from this raw contact should be forwarded directly to voice mail ('1') or not ('0'). To have an effect on the corresponding value of the aggregate contact, this field should be set at the time the raw contact is inserted. |
String | ACCOUNT_NAME |
read/write-once | The name of the account instance to which this row belongs, which when paired with
ACCOUNT_TYPE identifies a specific account.
For example, this will be the Gmail address if it is a Google account.
It should be set at the time the raw contact is inserted and never
changed afterwards. |
String | ACCOUNT_TYPE |
read/write-once |
The type of account to which this row belongs, which when paired with
To ensure uniqueness, new account types should be chosen according to the Java package naming convention. Thus a Google account is of type "com.google". |
String | DATA_SET |
read/write-once |
The data set within the account that this row belongs to. This allows
multiple sync adapters for the same account type to distinguish between
each others' data. The combination of This is empty by default, and is completely optional. It only needs to be populated if multiple sync adapters are entering distinct data for the same account type and account name. It should be set at the time the raw contact is inserted and never changed afterwards. |
String | SOURCE_ID |
read/write | String that uniquely identifies this row to its source account. Typically it is set at the time the raw contact is inserted and never changed afterwards. The one notable exception is a new raw contact: it will have an account name and type (and possibly a data set), but no source id. This indicates to the sync adapter that a new contact needs to be created server-side and its ID stored in the corresponding SOURCE_ID field on the phone. |
int | VERSION |
read-only | Version number that is updated whenever this row or its related data changes. This field can be used for optimistic locking of a raw contact. |
int | DIRTY |
read/write | Flag indicating that VERSION has changed, and this row needs
to be synchronized by its owning account. The value is set to "1" automatically
whenever the raw contact changes, unless the URI has the
CALLER_IS_SYNCADAPTER query parameter specified.
The sync adapter should always supply this query parameter to prevent
unnecessary synchronization: user changes some data on the server,
the sync adapter updates the contact on the phone (without the
CALLER_IS_SYNCADAPTER flag) flag, which sets the DIRTY flag,
which triggers a sync to bring the changes to the server.
|
String | SYNC1 |
read/write | Generic column provided for arbitrary use by sync adapters. The content provider stores this information on behalf of the sync adapter but does not interpret it in any way. |
String | SYNC2 |
read/write | Generic column for use by sync adapters. |
String | SYNC3 |
read/write | Generic column for use by sync adapters. |
String | SYNC4 |
read/write | Generic column for use by sync adapters. |
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
ContactsContract.RawContacts.Data | A sub-directory of a single raw contact that contains all of its
ContactsContract.Data rows. |
||||||||||
ContactsContract.RawContacts.DisplayPhoto | A sub-directory of a single raw contact that represents its primary display photo. |
||||||||||
ContactsContract.RawContacts.Entity |
A sub-directory of a single raw contact that contains all of its
|
||||||||||
ContactsContract.RawContacts.StreamItems |
A sub-directory of a single raw contact that contains all of its
|
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | AGGREGATION_MODE_DEFAULT | Aggregation mode: aggregate immediately after insert or update operation(s) are complete. | |||||||||
int | AGGREGATION_MODE_DISABLED | Aggregation mode: never aggregate this raw contact. |
|||||||||
int | AGGREGATION_MODE_IMMEDIATE | This constant was deprecated in API level 11. Aggregation is synchronous, this historic value is a no-op | |||||||||
int | AGGREGATION_MODE_SUSPENDED | Aggregation mode: aggregation suspended temporarily, and is likely to be resumed later. |
|||||||||
String | CONTENT_ITEM_TYPE | The MIME type of the results when a raw contact ID is appended to CONTENT_URI ,
yielding a subdirectory of a single person. |
|||||||||
String | CONTENT_TYPE | The MIME type of the results from CONTENT_URI when a specific
ID value is not provided, and multiple raw contacts may be returned. |
[Expand]
Inherited Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From interface
android.provider.BaseColumns
| |||||||||||
From interface
android.provider.ContactsContract.BaseSyncColumns
| |||||||||||
From interface
android.provider.ContactsContract.ContactNameColumns
| |||||||||||
From interface
android.provider.ContactsContract.ContactOptionsColumns
| |||||||||||
From interface
android.provider.ContactsContract.RawContactsColumns
| |||||||||||
From interface
android.provider.ContactsContract.SyncColumns
|
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
CONTENT_URI | The content:// style URI for this table, which requests a directory of raw contact rows matching the selection criteria. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Build a
CONTENT_LOOKUP_URI
style Uri for the parent ContactsContract.Contacts
entry of the given ContactsContract.RawContacts entry. | |||||||||||
TODO: javadoc
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
Aggregation mode: aggregate immediately after insert or update operation(s) are complete.
Aggregation mode: never aggregate this raw contact. The raw contact will not
have a corresponding Contacts
aggregate and therefore will not be included in
Contacts
query results.
For example, this mode can be used for a raw contact that is marked for deletion while waiting for the deletion to occur on the server side.
This constant was deprecated
in API level 11.
Aggregation is synchronous, this historic value is a no-op
Aggregation mode: aggregate at the time the raw contact is inserted/updated.
Aggregation mode: aggregation suspended temporarily, and is likely to be resumed later.
Changes to the raw contact will update the associated aggregate contact but will not
result in any change in how the contact is aggregated. Similar to
AGGREGATION_MODE_DISABLED
, but maintains a link to the corresponding
Contacts
aggregate.
This can be used to postpone aggregation until after a series of updates, for better performance and/or user experience.
Note that changing
AGGREGATION_MODE
from AGGREGATION_MODE_SUSPENDED
to
AGGREGATION_MODE_DEFAULT
does not trigger an aggregation pass, but any
subsequent
change to the raw contact's data will.
The MIME type of the results when a raw contact ID is appended to CONTENT_URI
,
yielding a subdirectory of a single person.
The MIME type of the results from CONTENT_URI
when a specific
ID value is not provided, and multiple raw contacts may be returned.
The content:// style URI for this table, which requests a directory of raw contact rows matching the selection criteria.
Build a CONTENT_LOOKUP_URI
style Uri
for the parent ContactsContract.Contacts
entry of the given ContactsContract.RawContacts
entry.