Android API之android.provider.ContactsContract.RawContacts
2015-02-28 12:44
393 查看
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.
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
by the change of the
Changes to the structured name, organization, phone number, email address, or nickname trigger a re-aggregation.
See also
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
are available at the time the raw contact is created:
Once
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.
Note the use of
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
are deleted, the
The invocation of
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
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:
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:
The best way to read a raw contact along with all the data associated with it is by using the
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.
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.
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
RawContactstable
by the change of the
CONTACT_IDfield, 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
AggregationExceptionsfor 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
Datavalues
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
Datavalues 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 = Lists.newArrayList(); ... 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
Contactsrow
are deleted, the
Contactsrow itself is also deleted automatically.
The invocation of
resolver.delete(...), does not immediately delete a raw contacts row. Instead, it sets the
DELETEDflag
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_SYNCADAPTERquery
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.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
Entitydirectory. 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
RawContacts类型 | 字段名字 | 读写权限 | 备注 |
long | _ID | 只读 | 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 | 只读 | The ID of the row in the ContactsContract.Contactstable that this raw contact belongs to. Raw contacts are linked to contacts by the aggregation process, which can be controlled by the AGGREGATION_MODEfield and AggregationExceptions. |
int | AGGERATION_MODE | 可读/可写 | A mechanism that allows programmatic control of the aggregation process. The allowed values areAGGREGATION_MODE_DEFAULT, AGGREGATION_MODE_DISABLEDand AGGREGATION_MODE_SUSPENDED. See also AggregationExceptions. |
int | DELETED | 可读/可写 | The "deleted" flag: "0" by default, "1" if the row has been marked for deletion. Whenandroid.content.ContentResolver.deleteis 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 ContactsContract.CALLER_IS_SYNCADAPTERquery parameter to finalize the data removal. |
int | TIMES_CONTACTED | 可读/可写 | 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 ContactsContract.Contacts.markAsContacted. |
long | LAST_TIME_CONTACTED | 可读/可写 | 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 ContactsContract.Contacts.markAsContacted. |
int | STARRED | 可读/可写 | 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 | 可读/可写 | A custom ringtone associated with a raw contact. Typically this is the URI returned by an activity launched with theandroid.media.RingtoneManager.ACTION_RINGTONE_PICKERintent. 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_RINGTONEinstead. |
int | SEND_TO_VOICEMAIL | 可读/可写 | 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 | 可读/写一次 | The name of the account instance to which this row belongs, which when paired with ACCOUNT_TYPEidentifies 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 | 可读/写一次 | The type of account to which this row belongs, which when paired with ACCOUNT_NAMEidentifies a specific account. It should be set at the time the raw contact is inserted and never changed afterwards. 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 | SOURCE_ID | 可读/可写 | 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, 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 | 只读 | 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 | 可读/可写 | Flag indicating that VERSIONhas 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 ContactsContract.CALLER_IS_SYNCADAPTERquery 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 | 可读/可写 | 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 | 可读/可写 | 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. |
相关文章推荐
- Android API之android.provider.ContactsContract.RawContacts
- Android API之android.provider.ContactsContract
- Android API之android.provider.ContactsContract.Contacts
- Android API之android.provider.ContactsContract.Contacts
- Android API之android.provider.ContactsContract.Contacts
- Android API之android.provider.ContactsContract.Data
- Android API之android.provider.ContactsContract
- Android API之android.provider.ContactsContract.Data
- import android.provider.ContactsContract 出错
- android.provider.ContactsContract.Contacts表中所有字段之详解
- android.provider.ContactsContract ㄧ些資料庫欄位
- import android.provider.ContactsContract 出错
- android.provider.ContactsContract.Contacts表中所有字段之详解
- 读取手机中的联系人信息(android.provider.ContactsContract)
- The import android provider.ContactsContract cannot be resolved
- Android通讯录查询篇--ContactsContract.Data 二(续)
- android api 完整翻译之Contacts Provider (学习安卓必知的api,中英文对照)
- Android通讯录查询篇--ContactsContract.Data 二
- Android通讯录查询篇--ContactsContract.Data 二(续)
- 【Android Api 翻译4】android api 完整翻译之Contacts Provider (学习安卓必知的api,中英文对照)