联系人Contact类解析

Contact类

public static class Contacts implements BaseColumns, ContactsColumns,

            ContactOptionsColumns, ContactNameColumns, ContactStatusColumns

 

对Contacts表共17项数据:
变量名                                            列名                                备注
 _ID                                                 _id
 LOOKUP_KEY                               lookup
                                                                     NAME_RAW_CONTACT_ID参照@1
 DISPLAY_NAME                             display_name                    在Contacts对列的描述为DISPLAY_NAME_PRIMARY
 PHOTO_ID                                     photo_id
 IN_VISIBLE_GROUP                       in_visible_group
 HAS_PHONE_NUMBER                   has_phone_number
 TIMES_CONTACTED                     times_contacted
 LAST_TIME_CONTACTED            last_time_contacted
 STARRED                                      starred
 CUSTOM_RINGTONE                    custom_ringtone
 SEND_TO_VOICEMAIL                    send_to_voicemail
 CONTACT_PRESENCE                    contact_presence
 CONTACT_STATUS                        contact_status
 CONTACT_STATUS_TIMESTAMP            contact_status_ts
 CONTACT_STATUS_RES_PACKAGE            contact_status_res_package
 CONTACT_STATUS_LABEL                contact_status_label
 CONTACT_STATUS_ICON                contact_status_icon
注意1：在Contacts对列的描述有NAME_RAW_CONTACT_ID，但没找到相应的变量和列名。
可能ContentResolver觉得把该项暴露给用户每什么意义，就把它隐藏起来了。该项应该是只给系统内部用的哦。
注意2：只有五项是可写TIMES_CONTACTED, LAST_TIME_CONTACTED, STARRED, CUSTOM_RINGTONE, SEND_TO_VOICEMAIL.
Operations

数据插入
    A Contact cannot be created explicitly. When a raw contact is inserted, the provider will first try to find a Contact representing the same person. 
    If one is found, the raw contact's CONTACT_ID column gets the _ID of the aggregate Contact. 
    If no match is found, the provider automatically inserts a new Contact 
    and puts its _ID into the CONTACT_ID column of the newly inserted raw contact.
    用户部能直接插入数据。数据的插入是由系统自动来完成的。
    
    当raw contact被插入或时，系统就会检查是否可以把该raw contact加到已经有的组（contact）。
    如果找到可以加入的组，就把组ID写到raw contact的CONTACT_ID这个数据项中。
    如果没找到就由系统重新创建一组，并把组ID写到raw contact的CONTACT_ID这个数据项中。
    如果raw contact的structured name, organization, phone number, email address, or nickname被改变。
    
    系统就会检查raw contact是否还属于raw contact的CONTACT_ID标记的那个组。
    如果发现raw contact不属于raw contact的CONTACT_ID标记的那个组。
    那么系统就会找是否可以把该raw contact加到已经有的其他组（contact）
    如果找到可以加入的组，就把组ID写到raw contact的CONTACT_ID这个数据项中。
    如果没找到就由系统重新创建一组，并把组ID写到raw contact的CONTACT_ID这个数据项中。
    注意：这的组是指contact（Aggregation of raw contact）
数据更新
    自动更新：当contact所包含的RawContacts的信息发生改变时，系统会对contact做相应的更新。
    手动强制更新：
    Only certain columns of Contact are modifiable: TIMES_CONTACTED, LAST_TIME_CONTACTED, STARRED, CUSTOM_RINGTONE, SEND_TO_VOICEMAIL. Changing any of these columns on the Contact also changes them on all constituent raw contacts.
    只有五项是可被用户直接更新。它们是TIMES_CONTACTED, LAST_TIME_CONTACTED, STARRED, CUSTOM_RINGTONE, SEND_TO_VOICEMAIL。
    当它们被手动强制更新时，contact所包含的RawContacts的相应项也会被一起更新。
数据删除
    Contacts文档说：
    Be careful with deleting Contacts! Deleting an aggregate contact deletes all constituent raw contacts.
    The corresponding sync adapters will notice the deletions of their respective raw contacts 
    and remove them from their back end storage.
    删除一个Contacts，会把它所包含所有raw contacts都删除掉。
    但是用下面语句居然删除不了任何Contacts.
    getContentResolver().delete(Contacts.CONTENT_URI, null, 
                    null);
    不过在删除Contacts的所有raw contacts后，Contacts也被删除了。
Query
        * If you need to read an individual contact, consider using CONTENT_LOOKUP_URI instead of CONTENT_URI.
        * If you need to look up a contact by the phone number, use PhoneLookup.CONTENT_FILTER_URI, which is optimized for this purpose.
        * If you need to look up a contact by partial name, e.g. to produce filter-as-you-type suggestions, use the CONTENT_FILTER_URI URI.
        * If you need to look up a contact by some data element like email address, nickname, etc, 
        use a query against the ContactsContract.Data table. The result will contain contact ID, name etc. 
可用如下语句进行查询：
        Cursor c=getContentResolver().query(Contacts.CONTENT_URI, null,
                null, null, Contacts.DISPLAY_NAME + " COLLATE NOCASE");
注意1：对于查单个contact信息时，可用CONTENT_LOOKUP_URI来进行查询
注意2：对于想通过电话号码查询时，可用PhoneLookup.CONTENT_FILTER_URI来查询。
具体参照《用PhoneLookup进行电话号码查询》
注意3：对于想通过名字的模糊查询来查询时，可以CONTENT_FILTER_URI URI来查询。
注意4: 对于想通过email address, nickname来查询时，可查询ContactsContract.Data表。
它的查询结果里面包含了contact ID, name等信息。具体可参考《raw contact子表数据查询》
注意5：可以使用CONTENT_STREQUENT_URI来查询starred和经常联系的联系人信息
关于Contact的Uri介绍.

CONTENT_LOOKUP_URI

public static final Uri CONTENT_LOOKUP_URI = Uri.withAppendedPath(CONTENT_URI, "lookup");

A content:// style URI for this table that should be used to create shortcuts or otherwise create long-term links to contacts. 
This URI should always be followed by a "/" and the contact's LOOKUP_KEY. It can optionally also have a "/" and last known contact ID appended after that. This "complete" format is an important optimization and is highly recommended.
As long as the contact's row ID remains the same, this URI is equivalent to CONTENT_URI. 
If the contact's row ID changes as a result of a sync or aggregation, this URI will look up the contact using indirect information (sync IDs or constituent raw contacts).
Lookup key should be appended unencoded - it is stored in the encoded form, ready for use in a URI.
例如下：
    content://com.android.contacts/contacts/lookup/0n/400
注意:"On"是lookUpKey，"400"是Contacts._ID
得到CONTENT_LOOKUP_URI的方式有：
        1,从数据库中取得lookUpKey，然后再合成lookUpUri
        Cursor c=getContentResolver().query(Contacts.CONTENT_URI, null,
                null, null, Contacts.DISPLAY_NAME + " COLLATE NOCASE");
        Long contactId=cursor.getLong(cursor.getColumnIndex(Contacts._ID));
        //注意这里的lookUpKey是从Contacts表中取的
        String lookUpKey=cursor.getString(cursor.getColumnIndex(Contacts.LOOKUP_KEY));
        
        Uri lookUpUri=Contacts.getLookupUri(contactId, lookUpKey);     
        Cursor c = context.getContentResolver().query(lookUpUri, null,
                null, null, Contacts.DISPLAY_NAME + " COLLATE NOCASE");
        2，先用contactId合成contactUri,再用contactUri然后再合成lookUpUri.
        Uri contactUri=ContentUris.withAppendedId(Contacts.CONTENT_URI, contactId);
        Uri lookUpUri=Contacts.getLookupUri(context.getContentResolver(), contactUri);
另外可以从lookUpUri得到contactUri。
public static Uri lookupContact (ContentResolver resolver, Uri lookupUri)
Since: API Level 5
Computes a content URI (see CONTENT_URI) given a lookup URI.
Returns null if the contact cannot be found.
这里返回的是具体一个联系人的CONTENT_URI比如：content://com.android.contacts/contacts/400

CONTENT_URI

 public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "contacts");

全部contacts
    全部contacts就是Contacts.CONTENT_URI（content://com.android.contacts/contacts）
某个人contacts
    具体某个人就是Contacts.CONTENT_URI/contactId的形式。
比如：
    content://com.android.contacts/contacts/400
某个人contacts可用如下方式合成
Uri contactUri=ContentUris.withAppendedId(Contacts.CONTENT_URI, contactId);
也可用它对具体一个人进行查询
Cursor c = context.getContentResolver().query(contentUri, null,

                null, null, Contacts.DISPLAY_NAME + " COLLATE NOCASE");

 

CONTENT_FILTER_URI

public static final Uri CONTENT_FILTER_URI = Uri.withAppendedPath(CONTENT_URI, "filter");

The content:// style URI used for "type-to-filter" functionality on the CONTENT_URI URI. 
The filter string will be used to match various parts of the contact name.
The filter argument should be passed as an additional path segment after this URI.
用于对名字进行模糊查询。
String name="robin";
Uri uri = Uri.withAppendedPath(Contacts.CONTENT_FILTER_URI, Uri.encode(name));
c=context.getContentResolver().query(uri, null,null,null,null);

CONTENT_STREQUENT_URI

 public static final Uri CONTENT_STREQUENT_URI = Uri.withAppendedPath(CONTENT_URI, "strequent");

The content:// style URI for this table joined with useful data from ContactsContract.Data, 
filtered to include only starred contacts and the most frequently contacted contacts. 
它也是用于对联系人进行查询，但是只返回starred和经常联系的联系人信息。
比如：
c=context.getContentResolver().query(Contacts.CONTENT_STREQUENT_URI, null,null,null,null);
返回的列和CONTENT_URI查询一样，也是17项数据。

CONTENT_STREQUENT_FILTER_URI

public static final Uri CONTENT_STREQUENT_FILTER_URI = Uri.withAppendedPath(CONTENT_STREQUENT_URI, "filter");

The content:// style URI used for "type-to-filter" functionality on the CONTENT_STREQUENT_URI URI. 
The filter string will be used to match various parts of the contact name. 
The filter argument should be passed as an additional path segment after this URI.
它是用于通过名字来对联系人进行模糊查询，但是只返回starred和经常联系的联系人信息。
比如：
String name="robin";
 Uri uri = Uri.withAppendedPath(Contacts.CONTENT_STREQUENT_FILTER_URI, Uri.encode(name));
 c=context.getContentResolver().query(uri, null,null,null,null);
返回的列和CONTENT_URI查询一样，也是17项数据。