Android API之android.provider.ContactsContract.Contacts

android.provider.ContactsContract.Contacts

对应contacts数据表。RawContacts的一个聚合(aggregate)代表同一个人。每个人在数据表contacts中有一个记录。

Operations

Insert

Contact不能直接/显式创建。插入一个RawContact时，provider首先查找是否存在一个Contact表示同一个人。如果存在，provider将Contacts._ID赋值给RawContacts.CONTACT_ID。如果不存在，provider插入一个新的Contact记录，并且将Contacts._ID赋值给RawContacts.CONTACT_ID。

Update

在Contact中，只有部分字段可以修改：TIMES_CONTACTED, LAST_TIME_CONTACTED, STARRED, CUSTOM_RINGTONE, SEND_TO_VOICEMAIL。修改其中任一字段会修改contact的所有成员(RawContact)。

Delete

删除Contact需谨慎。删除聚合contact会删掉它的所有成员(RawContacts)。SyncAdapter将通知删除相关的RawContacts。

Query 

读取某个特定的contact（我的理解是：已知ContactId），建议使用CONTENT_LOOKUP_URI。

根据电话号码查找contact，建议使用优化过的PhoneLookup.CONTENT_FILTER_URI。

根据部分名字查找contact，建议使用CONTENT_FILTER_URI。

根据类似email地址、昵称等数据查找contact，建议查找ContactsContract.Data表。结果含有ContactId、姓名等。

Columns

Contacts

译文说明：在本文中将constituent raw contacts翻译为“成员RawContact”。

 

数据类型	字段名	是否只读	备注
long	_ID	只读	Row ID. 建议使用LOOKUP_KEY
String	LOOKUP_KEY	只读	用于查找contact。在聚合或同步操作中RowId可能发生变化。
long	NAME_RAW_CONTACT_ID	只读	The ID of the raw contact that contributes the display name to the aggregate contact. During aggregation one of the constituent raw contacts is chosen using a heuristic: a longer name or a name with more diacritic marks or more upper case characters is chosen.
String	DISPLAY_NAME_PRIMARY	只读	Contact的display-name。属性值来源：RawContactId等于NAME_RAW_CONTACT_ID的RawContact的display-name。
long	PHOTO_ID	只读	外键，引用ContactsContract.Data表中拥有photo数据的那条记录。记录的Mime-Type是CommonDataKinds.Photo.CONTENT_ITEM_TYPE。聚合值是Mime-Type等于CommonDataKinds.Photo.IS_SUPER_PRIMARY那个值。
int	IN_VISIBLE_GROUP	只读	contact是否在UI上可见。1 - 至少一个RawContact可见。0 - 其他。
int	HAS_PHONE_NUMBER	只读	contact是否至少有一个电话号码。1 - 至少有一个电话号码。0 - 其他。
int	TIMES_CONTACTED	可读，可写	Contact的联系次数。赋值操作自动改变所有成员RawContact的属性。聚合操作时，自动计算：取所有成员RawContact中最大的联系次数。
long	LAST_TIME_CONTACED	可读，可写	Contact的最近联系时间。赋值时TIMES_CONTACTED自增。赋值操作自动改变所有成员RawContact的属性。聚合操作时，自动计算：取所有成员RawContact中最近的联系时间。
int	STARRED	可读，可写	Contact是否favorite。1 - favorite。0 - 其他。聚合操作时，自动计算：任一成员RawContact是favorite，那么这个属性就赋值1。赋值操作自动改变所有成员RawContact的属性。
String	CUSTOM_RINGTONE	可读，可写	给Contact设定的铃声。通常情况是从activity中返回的URI，且activity由android.media.RingtoneManager.ACTION_RINGTONE_PICKER启动。
int	SEND_TO_VOICEMAIL	可读，可写	来自Contact的呼叫是否应该直接转发到voiceMail。1 - 是。0 - 否。聚合操作时，自动计算：所有成员RawContact的值是1，那么这个属性赋值1。赋值操作自动改变所有成员RawContact的属性。
int	CONTACT_PRESENCE	只读	Contact IM呈现出来的状态（我理解为：离线、在线、离开、忙碌等）。聚合值为所有成员RawContact的highest presence。provider可能没有选择将这个属性值持久存储。期望是presence状态会有规律性的更新。
String	CONTACT_STATUS	只读	Contact的最近的状态。聚合值取所有成员RawContac中最近的值。
long	CONTACT_STATUS_TIMESTAMP	只读	产生(插入或更新)最近状态的时间。
String	CONTACT_STATUS_RES_PACKAGE	只读	包括当前状态label和icon的包。
long	CONTACT_STATUS_LABEL	只读	The resource ID of the label describing the source of contact status, e.g. "Google Talk". This resource is scoped by the CONTACT_STATUS_RES_PACKAGE.
long	CONTACT_STATUS_ICON	只读	The resource ID of the icon for the source of contact status. This resource is scoped by the CONTACT_STATUS_RES_PACKAGE.