Android 2.0以後的Contacts API–ContactsContract

連絡人資訊的儲存結構：

從Android 2.0(API Level 5)開始，Android平台提供了一個改進的Contacts API，以適應一個連絡人可以有多個帳戶的需求，比如說手機通訊錄和GMAIL通訊錄，兩個通訊錄中的兩條記錄可以是同一個人。新的Contacts API主要是由ContactsContract及其相關的類來管理，舊的API(android.provider.Contacts）已不贊成使用，但為了相容仍可以使用，只不過像以前一樣，只能返回第一個帳戶的資訊。

在新的Contacts API中，連絡人資料被放到三張表中：Contacts、RawContacts和Data。這樣可以協助系統更好地儲存與管理一個連絡人的多個帳戶的資訊。

Data：

Data表格儲存體了連絡人的詳細資料，表中的每一行儲存一個特定類型的資訊，比如Email、Address或Phone。每一行通過一個mimetype_id的欄位來表示該行儲存的是什麼類型的資料，該欄位引用了mimetyps表，此表格儲存體了常用的資料類型。Data表的欄位主要有：

mimetype_id 表示該行儲存的資訊的類型
raw_contact_id 表示該行所屬的RawContact
is_primary 多個data資料群組成一個raw contact，該欄位表示此data是否是其所屬的raw contact的主data，即其display name會作為raw contact的display name
is_super_primary 該data是否是其所屬的contact的主data，如果is_super_primary為1則is_primary一定為1
data1~data15 15個資料欄位，對於不同類型的資訊，表示不同的含義，ContactsContract.CommomDataKinds類中定義了與常用的資料類型相對應的一些類，這些類中分別定義了相應資料類型中這些欄位表示的含義。一般data1表是主資訊（如電話，Email地址等），data2表示副資訊，data15表示Blob資料。
data_sync1~data_sync4 sync_adapter要用的欄位（sync_adapter用於資料的同步，比如你手機中的Gmail帳戶與Google伺服器的同步）。
data_version 資料的版本，用於資料的同步。

 

RawContact：

RawContact表中的一行儲存Data表中一些資料行的集合及一些其他的資訊，表示一個連絡人某一特定帳戶的資訊，比如Facebook或Exchange的一個連絡人。

當插入一個raw contact或當一個raw contact所屬的一個data改變時，系統會檢查這個raw contact跟其他的raw contact是否可以匹配（比如如果兩個raw contact的data包含相同的電話號碼或名字），如果匹配他們就會被綜合到一起，也就是說他們會屬於同一個cantact，表現為在RawContact表中他們引用的cantact_id是一樣的。

連絡人姓名、組織、電話號碼、Email或暱稱的改變會引發raw contact的重新彙總。有兩個方法控制彙總的行為Aggregaton Mode與ContactsContract.AggregationExceptions。

Aggregaton Mode：

RawContact表中有一個欄位aggregation_mode，通過向特定raw contact行中插入這個欄位可以修改系統對這個raw contact的彙總行為，其允許的值如下：

AGGREGATION_MODE_DEFAULT：正常模式，允許自動彙總；
AGGREGATION_MODE_DISABLE：不允許彙總；
AGGREGATION_MODE_SUSPENDED：當一個raw contact的aggregation mode修改為suspended時，如果其已是一個已彙總的contact的一部分，那麼它仍會保持與原來彙總到一起的raw contact的關係，即使它已改變不再跟其他raw contact匹配。

AGGREGATIONEXCEPTIONS：

在資料庫中存在一個表：agg_exceptions。通過欄位raw_contact_id1、raw_contact_id2、mode儲存兩個raw contact彙總的方法，系統定義的彙總行為有3個：

TYPE_AUTOMATIC=0　　由系統決定彙總行為，預設值。
TYPE_KEEP_SEPARATE=2　　不彙總
TYPE_KEEP_TOGETHER=1　　彙總

 

Contact：

Contact表中的一行表示一個連絡人，它是RawContact表中的一行或多行的資料的組合，這些RawContact表中的行表示同一個人的不同的帳戶資訊。Contact中的資料由系統組合RawContact表中的資料自動產生。

不可以直接向這個表中插入資料，當一個raw contact被插入的時候，系統會首先尋找Contact表看是否有記錄跟插入的raw contact表示同一個人，如果找到了，則把找到的這個contact的_ID插入raw contact記錄的CONTACT_ID欄位，如果沒有找到，則系統自動插入一個Contact記錄並把它的_ID插入新插入的raw contact的CONTACT_ID列。

Contact表中只有TIMES_CONTACTED、LAST_TIME_CONTACTED、STARRED、CUSTOM_RINGTONE、SENE_TO_VOICEMAIL列可更改，這些列的更改會導致相應的raw contact被更改。

當刪除Contact表中的記錄時，會刪除一個連絡人的所有帳戶的資訊，也就是說，其對應的所有raw contacts也會被刪除，各raw contact對應的data也就被刪除了，sync adapter同步時也會刪除伺服器端的相應記錄。

如果需要讀取一個連絡人的資訊用CONTENT_LOOKUP_RUI代替CONTENT_URI（見後面）；

如果需要通過電話號碼尋找一個連絡人，用PhoneLookup.CONTENT_FIILTER_URI，這個URI為這個目的進行了最佳化；

如果需要通過部分名字的匹配尋找，用CONTENT_FILTER_URI；

如果需要通過email，address等資訊尋找，尋找表ContactsContract.Data，結果包含contact ID，名字...

 

android.provider.ontactsContract.Data類

其定義如下：

 public final static class Data implements DataColumnsWithJoins {
private Data() {}
public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "data");
public static final String CONTENT_TYPE = "vnd.android.cursor.dir/data";
//This flag is useful (currently) only for vCard exporter in Contacts app
        public static final String FOR_EXPORT_ONLY = "for_export_only";
/*Build a CONTENT_LOOKUP_URI style Uri for the parent ContactsContract.Contacts entry of the given ContactsContract.Data entry.*/
public static Uri getContactLookupUri(ContentResolver resolver, Uri dataUri) {...}
    }

Data類定義了CONTENT_URI及CONTENT_TYPE，主要是繼承了DataColumnsWithJoins介面中的欄位。DataColumnsWithJoins定義如下：

protected interface DataColumnsWithJoins extends BaseColumns, DataColumns, StatusColumns,
            RawContactsColumns, ContactsColumns, ContactNameColumns, ContactOptionsColumns,
            ContactStatusColumns {
    }

該介面只是綜合了一些介面，其中：

BaseColumns定義了_ID與_COUNT欄位，ContentProvider查詢中都要用到的欄位。

DataColumns定義了與Data表中欄位一一對應的常量

RawContactsColumns, ContactsColumns, ContactNameColumns, ContactOptionsColumns表示RawContact與Contact中的一些欄位，定義到此類中以方便訪問。

由於連絡人的資訊都是按類別儲存到了這個Data表中，所以我們要尋找連絡人的資訊只需要查這個表。Data類中的Data.CONTACT_ID與Data.RAW_CONTACT_ID分別表示該表項對應的連絡人在Contact與RawContract表中的ID，我們只需要知道某一個連絡人的contactId或rawContractId，並根據其尋找的資料的類型就可以查到相應類型的資訊。

Cursor c = getContentResolver().query(Data.CONTENT_URI,
new String[] {Data._ID, Phone.NUMBER, Phone.TYPE, Phone.LABEL},
          Data.CONTACT_ID + "=?" + " AND "
                  + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'",
new String[] {String.valueOf(contactId)}, null);

以上代碼根據連絡人的contractId，並通過設定其MIMETYPE為Phone.CONTENT_ITEM_TYPE查到了該連絡人的電話號碼，把Data.CONTACT_ID換為Data.RAW_CONTACT_ID即可尋找相應rawContactId對應的電話號碼。其中用到了Phone.CONTENT_ITEM_TYPE，這是什麼呢？

CommonDataKinds類

在前面講Data表的結構時講到，Data的data1~data15欄位用於儲存各類型的資料資訊，那麼這15個欄位分別表示什麼資訊呢？

前面提到了，Data表中有一個mimetype_id欄位，通過這個欄位關聯mimetypes表表示該行代表的資訊類型，因為Data表中的每一行可以表示如Phone或Address等不同類型的資訊，所以對於不同類型的資訊，data1~data15這15列表示不同的含義，如果要靠記憶記住這15列對於特定的類型分別表示什麼意義自然不行，於是Google就預定義了一些類，每一個類對應一些預先定義好的資料類型，在每個類中定義了一些語義地、方便記憶的常量，用來對應這15個欄位，比如在CommonDataKinds.Email類中有如下定義

public static final String ADDRESS = DATA1;
public static final String DISPLAY_NAME = DATA4;

DATA1與DATA4為繼承自DataColumns中的常量，在DataColumns中是這樣定義的：

public static final String DATA1 = "data1";
public static final String DATA4 = "data4";

這樣，當於們要尋找Email地址時，只需要通過ContactsContract.CommonDataKinds.Email.ADDRESS引用，而不需要知道它是儲存在Data表中的data1列中。

回到上一個問題，上面查詢電話號碼的例子中用到了Phone.CONTENT_ITEM_TYPE，即是表示CommonDataKinds.Phone.CONTENT_ITEM_TYPE，在Phone類中有如下定義

public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/phone_v2";

vnd.android.cursor.item/phone_v2 就是表示Data表中相應的行儲存的是電話號碼的資訊，通過相應類型（如Phone、Email）的CONTENT_ITEM_TYPE，我們就可以指定要查詢的MIMETYPE，即要查詢的資料類型。

其實在上面的例子中還有更簡單的方法：

Cursor phone = getContentResolver().query(ContactsContract.CommonDataKinds.Phone.CONTENT_URI,
new String[] { CommonDataKinds.Phone.NUMBER }, CommonDataKinds.Phone.CONTACT_ID + " =? ",
new String[] { String.valueOf(contactId) }, null);

只需把query的第一個參數處傳遞想尋找的資料類型的相應的類中的CONTENT_URI就可以了。

 

 Lookup Key

在新的Contact API中，為contact引入了lookup key的概念，當你的程式需要儲存對連絡人的引用時，用lookup key而別用row id，lookup key是contacts表中的一列，當你有一個lookup key時，可以這樣構造一個Uri：

Uri lookupUri = Uri.withAppendedPath(Contacts.CONTENT_LOOKUP_URI, lookupKey);

然後用這個Uri查詢：

Cursor c = getContentResolver().query(lookupUri, new String[]{Contacts.DISPLAY_NAME}, ...);
try {
    c.moveToFirst();
    String displayName = c.getString(0);
} finally {
    c.close();
}

用lookup key 而不用row id的原因是因為row id容易改變，使用者把原先兩個連絡人合并成一個或因為同步的問題都會導致row id的改變。lookup key是一個字串，它由raw contact的標識串連組成。

使用row id會比使用lookup key效率高，你可以同時儲存二者，然後聯合二者產生一個lookup uri：

Uri lookupUri = getLookupUri(contactId, lookupKey)

當同時有row id跟lookup key時，系統會優先以row id查詢，如果無尋找結果或找到的結果跟lookup key不匹配，則再用lookup key尋找。

 

 

 

初學android，連android代碼都沒寫過幾行，想學習一下Contact API，發現說2.0後API改了，2.0以前的機子基本上也被淘汰了吧，就只看一下2.0以後的API吧，在網上找一點有用的資料都沒有，找來找去就那幾個文章，都可以說是SDK上的例子，本想找點參考的，最後發現還是只有SDK，看的暈頭轉行的，只有了一些最基本的理解，像跟IM有關的StatusColumns之類的還有Directory等就只粗略看了一眼就過去了。畢竟剛接觸android，SDK的文檔即使每一句話都能看懂也不太瞭解意思，不知道在哪用，先把看懂的記一下吧，免得以後又忘了。只是把SDK中分散到各頁面的東西綜合了一下。有錯的方希望別誤導了人。