android联系人信息的存储结构

从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表的字段主要有：

[java]  view plain copy

1. mimetype_id 表示该行存储的信息的类型  
2. raw_contact_id 表示该行所属的RawContact  
3. is_primary 多个data数据组成一个raw contact，该字段表示此data是否是其所属的raw contact的主data，即其display name会作为raw contact的display name  
4. is_super_primary 该data是否是其所属的contact的主data，如果is_super_primary为1则is_primary一定为1  
5. data1~data15 15个数据字段，对于不同类型的信息，表示不同的含义，ContactsContract.CommomDataKinds类中定义了与常用的数据类型相对应的一些类，这些类中分别定义了相应数据类型中这些字段表示的含义。一般data1表是主信息（如电话，Email地址等），data2表示副信息，data15表示Blob数据。  
6. data_sync1~data_sync4 sync_adapter要用的字段（sync_adapter用于数据的同步，比如你手机中的Gmail帐户与Google服务器的同步）。  
7. 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：

[java]  view plain copy

1. RawContact表中有一个字段aggregation_mode，通过向特定raw contact行中插入这个字段可以修改系统对这个raw contact的聚合行为，其允许的值如下：  
2. AGGREGATION_MODE_DEFAULT：正常模式，允许自动聚合；  
3. AGGREGATION_MODE_DISABLE：不允许聚合；  
4. 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个：

[java]  view plain copy

1. TYPE_AUTOMATIC=0　　由系统决定聚合行为，默认值。  
2. TYPE_KEEP_SEPARATE=2　　不聚合  
3. 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类

其定义如下：

[java]  view plain copy

1. public final static class Data implements DataColumnsWithJoins {  
2.         private Data() {}  
3.         public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "data");  
4.         public static final String CONTENT_TYPE = "vnd.android.cursor.dir/data";  
5.     //This flag is useful (currently) only for vCard exporter in Contacts app         public static final String FOR_EXPORT_ONLY = "for_export_only";  
6.     /*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) {...}  
7.     }  

Data类定义了CONTENT_URI及CONTENT_TYPE，主要是继承了DataColumnsWithJoins接口中的字段。DataColumnsWithJoins定义如下：

[java]  view plain copy

1. protected interface DataColumnsWithJoins extends BaseColumns, DataColumns, StatusColumns,  
2.             RawContactsColumns, ContactsColumns, ContactNameColumns, ContactOptionsColumns,  
3.             ContactStatusColumns {  
4.     }  

该接口只是综合了一些接口，其中：

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，并根据其查找的数据的类型就可以查到相应类型的信息。

[java]  view plain copy

1. Cursor c = getContentResolver().query(Data.CONTENT_URI,  
2.           new String[] {Data._ID, Phone.NUMBER, Phone.TYPE, Phone.LABEL},  
3.           Data.CONTACT_ID + "=?" + " AND "  
4.                   + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'",  
5.           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类中有如下定义

[java]  view plain copy

1. public static final String ADDRESS = DATA1;  

[java]  view plain copy

1. public static final String DISPLAY_NAME = DATA4;  

DATA1与DATA4为继承自DataColumns中的常量，在DataColumns中是这样定义的：

[java]  view plain copy

1. public static final String DATA1 = "data1";  

[java]  view plain copy

1. public static final String DATA4 = "data4";  

这样，当于们要查找Email地址时，只需要通过ContactsContract.CommonDataKinds.Email.ADDRESS引用，而不需要知道它是存储在Data表中的data1列中。

回到上一个问题，上面查询电话号码的例子中用到了Phone.CONTENT_ITEM_TYPE，即是表示CommonDataKinds.Phone.CONTENT_ITEM_TYPE，在Phone类中有如下定义

[java]  view plain copy

1. 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，即要查询的数据类型。

其实在上面的例子中还有更简单的方法：

[java]  view plain copy

1. Cursor phone = getContentResolver().query(ContactsContract.CommonDataKinds.Phone.CONTENT_URI,  
2.     new String[] { CommonDataKinds.Phone.NUMBER }, CommonDataKinds.Phone.CONTACT_ID + " =? ",  
3.     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：

[java]  view plain copy

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

然后用这个Uri查询：

[java]  view plain copy

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

用lookup key 而不用row id的原因是因为row id容易改变，用户把原先两个联系人合并成一个或因为同步的问题都会导致row id的改变。lookup key是一个字符串，它由raw contact的标识连接组成。

使用row id会比使用lookup key效率高，你可以同时保存二者，然后联合二者生成一个lookup uri：

[java]  view plain copy

1. Uri lookupUri = getLookupUri(contactId, lookupKey)  

当同时有row id跟lookup key时，系统会优先以row id查询，如果无查找结果或找到的结果跟lookup key不匹配，则再用lookup key查找。

 

在网上看到的读取所有联系人姓名与电话的代码都是这样的：

[java]  view plain copy

1. ContentResolver cr = getContentResolver();     Cursor cursor = cr.query(ContactsContract.Contacts.CONTENT_URI, null, null, null, null);  while (cursor.moveToNext())    
2. {    
3.     // 取得联系人名字      int nameFieldColumnIndex = cursor.getColumnIndex(PhoneLookup.DISPLAY_NAME);    
4.     String name = cursor.getString(nameFieldColumnIndex);    
5.     string += (name);    
6.     
7.     // 取得联系人ID      String contactId = cursor.getString(cursor.getColumnIndex(ContactsContract.Contacts._ID));    
8.     Cursor phone = cr.query(ContactsContract.CommonDataKinds.Phone.CONTENT_URI, null, ContactsContract.CommonDataKinds.Phone.CONTACT_ID + " = "    
9.             + contactId, null, null);    
10.     
11.     // 取得电话号码(可能存在多个号码)      while (phone.moveToNext())    
12.     {    
13.         String strPhoneNumber = phone.getString(phone.getColumnIndex(ContactsContract.CommonDataKinds.Phone.NUMBER));    
14.         string += (":" + strPhoneNumber);    
15.     }    
16.     string += "\n";    
17.     phone.close();    
18. }    
19. cursor.close();  

如果有n个联系人且每个联系人都存有电话号码的话，就得查询n+1次。

在园子里看到一个帖子说可以通过

[java]  view plain copy

1. Uri.withAppendedPath(PhoneLookup.CONTENT_FILTER_URI, "*")  

取得所有联系人的信息，我在Android 4.0模拟器跟2.3.7的真机上测试都不成功。

联系人的各种类型的信息都存储在Data表中，所以查询Data表并限制其MIMETYPE为Phone.CONTENT_ITEM_TYPE即可以查到所有姓名与电话

[java]  view plain copy

1. Cursor phone = cr.query(ContactsContract.CommonDataKinds.Phone.CONTENT_URI, new String[] {  
2.                 CommonDataKinds.Phone.NUMBER, CommonDataKinds.Phone.DISPLAY_NAME }, null, null, null);  

上述代码可以查到所有联系人的姓名与电话，但是如果直接挨个输出的话会有问题，如果一个人存储了两个电话号码的话，在Data表中会有两条记录，比如一个叫张三的人，存储了他两个电话：11111，22222。那么输出结果中会有两条关于张三的记录，并不会合并到一起，所以我想到先把cursor查询到的所有数据存储到Map里，以DISPLAY_NAME为键，以NUMBER组成的List为值，即

[java]  view plain copy

1. HashMap<String,ArrayList<String>>   

于是有了如下代码：

[java]  view plain copy

1. ContentResolver cr = getContentResolver();  
2. HashMap<String,ArrayList<String>> hs=new HashMap<String,ArrayList<String>>();  
3. Cursor phone = cr.query(ContactsContract.CommonDataKinds.Phone.CONTENT_URI, new String[] {  
4. 　　　　CommonDataKinds.Phone.NUMBER, CommonDataKinds.Phone.DISPLAY_NAME }, null, null, null);while (phone.moveToNext()) {  
5. 　　String strPhoneNumber = phone.getString(phone.getColumnIndex(ContactsContract.CommonDataKinds.Phone.NUMBER));  
6. 　　String name = phone.getString(phone.getColumnIndex(CommonDataKinds.Phone.DISPLAY_NAME));  
7. 　　ArrayList<String> ad=hs.get(name);　　if(ad==null){  
8. 　　　　ad=new ArrayList<String>();  
9. 　　　　ad.add(strPhoneNumber);  
10. 　　　　hs.put(dis, ad);  
11. 　　}　　else 　　　　ad.add(strPhoneNumber);  
12. }  
13. phone.close();  

这样就可以解决一个姓名对应多个号码的问题，但还有问题，可能是两个联系人同名，但他们属于不同的联系人，在数据库中表现为有不同的contact_id，那么可以将上述代码修改一下，将projection参数处添加上ContactsContract.CommonDataKinds.Phone.CONTACT_ID，然后把Map改为以contact_id为建，以DISPLAY_NAME与NUMBER组成的LIST为值，把DISPLAY_NAME统一存储为LIST的第一项。当然也可以定义一个类，包含姓名字段及电话号码组成的LIST字段，电话号码的LIST中的元素还可以是Map，以号码的TYPE为键。

1.加入读写权限

[java]  view plain copy

1. <uses-permission android:name="android.permission.READ_CONTACTS" />    
2. <uses-permission android:name="android.permission.WRITE_CONTACTS" />   

联系人信息Uri：

content://com.android.contacts/contacts 

 

联系人电话Uri：

content://com.android.contacts/data/phones 

 

联系人Email Uri：

content://com.android.contacts/data/emails 

     

（推荐）也可以这样获取联系人信息Uri：Uri uri =  ContactsContract.Contacts.CONTENT_URI;

   

2.查询与添加联系人的操作（单元测试用例）

   

[java]  view plain copy

1. public class ContactTest extends AndroidTestCase     
2. {    
3.     private static final String TAG = "ContactTest";    
4.         
5.     /**  
6.      * 获取通讯录中所有联系人的简单信息  
7.      * @throws Throwable  
8.      */    
9.     public void testGetAllContact() throws Throwable    
10.     {    
11.         //获取联系人信息的Uri    
12.         Uri uri =  ContactsContract.Contacts.CONTENT_URI;    
13.         //获取ContentResolver    
14.         ContentResolver contentResolver = this.getContext().getContentResolver();    
15.         //查询数据，返回Cursor    
16.         Cursor cursor = contentResolver.query(uri, null, null, null, null);    
17.         while(cursor.moveToNext())    
18.         {    
19.             StringBuilder sb = new StringBuilder();    
20.             //获取联系人的ID    
21.             String contactId = cursor.getString(cursor.getColumnIndex(ContactsContract.Contacts._ID));      
22.             //获取联系人的姓名    
23.             String name = cursor.getString(cursor.getColumnIndex(ContactsContract.Contacts.DISPLAY_NAME));     
24.             //构造联系人信息    
25.             sb.append("contactId=").append(contactId).append(",Name=").append(name);    
26.             //查询电话类型的数据操作    
27.             Cursor phones = contentResolver.query(ContactsContract.CommonDataKinds.Phone.CONTENT_URI,      
28.                     null,      
29.                     ContactsContract.CommonDataKinds.Phone.CONTACT_ID +" = "+ contactId,      
30.                     null, null);      
31.             while(phones.moveToNext())    
32.             {    
33.                 String phoneNumber = phones.getString(phones.getColumnIndex(    
34.                         ContactsContract.CommonDataKinds.Phone.NUMBER));    
35.                 //添加Phone的信息    
36.                 sb.append(",Phone=").append(phoneNumber);    
37.             }    
38.             phones.close();    
39.                 
40.             //查询Email类型的数据操作    
41.             Cursor emails = contentResolver.query(ContactsContract.CommonDataKinds.Email.CONTENT_URI,      
42.                        null,      
43.                        ContactsContract.CommonDataKinds.Email.CONTACT_ID + " = " + contactId,      
44.                        null, null);      
45.             while (emails.moveToNext())     
46.             {      
47.                 String emailAddress = emails.getString(emails.getColumnIndex(    
48.                         ContactsContract.CommonDataKinds.Email.DATA));    
49.                 //添加Email的信息    
50.                 sb.append(",Email=").append(emailAddress);    
51.             }     
52.             emails.close();    
53.             Log.i(TAG, sb.toString());    
54.         }    
55.         cursor.close();    
56.     }    
57.         
58.     /**添加联系人的第一种方法：  
59.      * 首先向RawContacts.CONTENT_URI执行一个空值插入，目的是获取系统返回的rawContactId   
60.      * 这时后面插入data表的依据，只有执行空值插入，才能使插入的联系人在通讯录里面可见  
61.      */    
62.     public void testInsert()     
63.     {    
64.         ContentValues values = new ContentValues();    
65.         //首先向RawContacts.CONTENT_URI执行一个空值插入，目的是获取系统返回的rawContactId     
66.         Uri rawContactUri = this.getContext().getContentResolver().insert(RawContacts.CONTENT_URI, values);    
67.         //获取id    
68.         long rawContactId = ContentUris.parseId(rawContactUri);    
69.         //往data表入姓名数据    
70.         values.clear();    
71.         values.put(Data.RAW_CONTACT_ID, rawContactId); //添加id    
72.         values.put(Data.MIMETYPE, StructuredName.CONTENT_ITEM_TYPE);//添加内容类型（MIMETYPE）    
73.         values.put(StructuredName.GIVEN_NAME, "凯风自南");//添加名字，添加到first name位置    
74.         this.getContext().getContentResolver().insert(android.provider.ContactsContract.Data.CONTENT_URI, values);    
75.         //往data表入电话数据    
76.         values.clear();    
77.         values.put(Data.RAW_CONTACT_ID, rawContactId);    
78.         values.put(Data.MIMETYPE, Phone.CONTENT_ITEM_TYPE);    
79.         values.put(Phone.NUMBER, "13921009789");    
80.         values.put(Phone.TYPE, Phone.TYPE_MOBILE);    
81.         this.getContext().getContentResolver().insert(android.provider.ContactsContract.Data.CONTENT_URI, values);    
82.         //往data表入Email数据    
83.         values.clear();    
84.         values.put(Data.RAW_CONTACT_ID, rawContactId);    
85.         values.put(Data.MIMETYPE, Email.CONTENT_ITEM_TYPE);    
86.         values.put(Email.DATA, "kesenhoo@gmail.com");    
87.         values.put(Email.TYPE, Email.TYPE_WORK);    
88.         this.getContext().getContentResolver().insert(android.provider.ContactsContract.Data.CONTENT_URI, values);    
89.     }    
90.         
91.     /**添加联系人的第二种方法：  
92.      * 批量添加联系人  
93.      * @throws Throwable  
94.      */    
95.     public void testSave() throws Throwable    
96.     {    
97.         //官方文档位置：reference/android/provider/ContactsContract.RawContacts.html    
98.         //建立一个ArrayList存放批量的参数    
99.         ArrayList<ContentProviderOperation> ops = new ArrayList<ContentProviderOperation>();    
100.         int rawContactInsertIndex = ops.size();    
101.         ops.add(ContentProviderOperation.newInsert(RawContacts.CONTENT_URI)    
102.                 .withValue(RawContacts.ACCOUNT_TYPE, null)    
103.                 .withValue(RawContacts.ACCOUNT_NAME, null)    
104.                 .build());    
105.         //官方文档位置：reference/android/provider/ContactsContract.Data.html    
106.         //withValueBackReference后退引用前面联系人的id    
107.         ops.add(ContentProviderOperation.newInsert(android.provider.ContactsContract.Data.CONTENT_URI)    
108.                 .withValueBackReference(Data.RAW_CONTACT_ID, rawContactInsertIndex)    
109.                 .withValue(Data.MIMETYPE, StructuredName.CONTENT_ITEM_TYPE)    
110.                 .withValue(StructuredName.GIVEN_NAME, "小明")    
111.                 .build());    
112.         ops.add(ContentProviderOperation.newInsert(android.provider.ContactsContract.Data.CONTENT_URI)    
113.                  .withValueBackReference(Data.RAW_CONTACT_ID, rawContactInsertIndex)    
114.                  .withValue(Data.MIMETYPE, Phone.CONTENT_ITEM_TYPE)    
115.                  .withValue(Phone.NUMBER, "13671323809")    
116.                  .withValue(Phone.TYPE, Phone.TYPE_MOBILE)    
117.                  .withValue(Phone.LABEL, "手机号")    
118.                  .build());    
119.         ops.add(ContentProviderOperation.newInsert(android.provider.ContactsContract.Data.CONTENT_URI)    
120.                  .withValueBackReference(Data.RAW_CONTACT_ID, rawContactInsertIndex)    
121.                  .withValue(Data.MIMETYPE, Email.CONTENT_ITEM_TYPE)    
122.                  .withValue(Email.DATA, "kesen@gmail.com")    
123.                  .withValue(Email.TYPE, Email.TYPE_WORK)    
124.                  .build());    
125.         ContentProviderResult[] results = this.getContext().getContentResolver()    
126.             .applyBatch(ContactsContract.AUTHORITY, ops);    
127.         for(ContentProviderResult result : results)    
128.         {    
129.             Log.i(TAG, result.uri.toString());    
130.         }    
131.     }    
132. }