ContactsContract.RawContacts

public static final class ContactsContract.RawContacts
extends Object implements BaseColumns, ContactsContract.RawContactsColumns, ContactsContract.ContactOptionsColumns, ContactsContract.ContactNameColumns, ContactsContract.SyncColumns

原始联系人表的常量，其中包含每个已同步帐户中每个人的一行联系信息。 同步适配器和联系人管理应用程序是此API的主要使用者。

Aggregation

只要插入一个原始联系人或者其组成数据发生变化，提供商就会检查原始联系人是否与其他现有原始联系人匹配，如果是，则会将其与其他联系人进行汇总。 该聚合反映在ContactsContract.RawContacts表中，由CONTACT_ID字段的更改引起，该字段是对聚合联系人的引用。

对结构化名称，组织，电话号码，电子邮件地址或昵称的更改会触发重新聚合。

另请参阅 ContactsContract.AggregationExceptions了解以编程方式控制聚合的机制。

Operations

Insert

原始联系人可以增量或批量插入。 增量方法更传统但效率更低。 只有在创建原始联系人时没有ContactsContract.RawContacts.Data值可用的情况下才应使用它：

 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);
 

一旦ContactsContract.RawContacts.Data值可用，请插入这些值。 例如，以下是如何插入名称的方法：

 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);
 

批量方法是迄今为止优选的。 它将原始联系人及其组成数据行插入单个数据库事务中，并最多导致一次聚合传递。

 ArrayList<ContentProviderOperation> ops =
          new ArrayList<ContentProviderOperation>();
 ...
 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);
 

请注意，使用 withValueBackReference(String, int)来引用在第一个操作中插入的原始联系人的尚未知的索引值。

Update

原始联系人可以逐步更新或批量更新。 应尽可能使用批处理模式。 程序和考虑类似于上面记载的插入程序。

Delete

当原始联系人被删除时，其所有Data行以及StatusUpdates，AggregationExceptions，PhoneLookup行都会自动删除。 当与Contacts行关联的所有原始联系人都被删除时， Contacts行本身也会自动删除。

调用resolver.delete(...) ，不会立即删除原始联系人行。 相反，它会在原始联系人上设置DELETED标志，并将原始联系人DELETED联系人中删除。 同步适配器然后从服务器删除原始联系人并通过再次调用resolver.delete(...)并传递CALLER_IS_SYNCADAPTER查询参数来完成电话端删除。

一些同步适配器是只读的，这意味着它们只将服务器端的更改同步到手机，但不会相反。 如果其中一个原始联系人被标记为删除，它将保留在电话上。 但是它会被有效地隐藏，因为它不会成为任何聚合联系人的一部分。

Query

很容易找到联系人中的所有原始联系人：

 Cursor c = getContentResolver().query(RawContacts.CONTENT_URI,
          new String[]{RawContacts._ID},
          RawContacts.CONTACT_ID + "=?",
          new String[]{String.valueOf(contactId)}, null);
 

要在特定帐户中查找原始联系人，您可以将帐户名称和类型放入选择中，或将其作为查询参数传递。 后一种方法是可取的，尤其是当您可以重用URI时：

 Uri rawContactUri = RawContacts.CONTENT_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);
 

读取原始联系人以及与其关联的所有数据的最佳方式是使用ContactsContract.RawContacts.Entity目录。 如果原始联系人具有数据行，则实体游标将为每个数据行包含一行。 如果原始联系人没有数据行，则光标仍将包含一行与原始联系人级别信息。

 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

Summary

Inherited constants
From interface android.provider.BaseColumns String _COUNT 目录中的行数。 String _ID 一行的唯一ID。
From interface android.provider.ContactsContract.RawContactsColumns String ACCOUNT_TYPE_AND_DATA_SET 帐户类型和数据集的串联（用正斜杠分隔） - 如果数据集为空，则与帐户类型相同。 String AGGREGATION_MODE 此联系人的聚合模式。 String BACKUP_ID 其帐户中每个raw_contact的持久性唯一标识。 String CONTACT_ID 这个数据属于 _ID的引用。 String DATA_SET 该行属于该帐户内的数据集。 String DELETED “已删除”标志：默认为“0”，如果该行已被标记为删除，则为“1”。 String METADATA_DIRTY 表示原始联系人的元数据已更改的标志，并且其元数据需要由服务器同步。 String RAW_CONTACT_IS_READ_ONLY “只读”标志：默认情况下为“0”，如果除了同步适配器以外不能修改或删除该行，则为“1”。 String RAW_CONTACT_IS_USER_PROFILE 反映此原始联系人是否属于用户的个人资料条目的标志。
From interface android.provider.ContactsContract.ContactOptionsColumns String CUSTOM_RINGTONE 与联系人关联的自定义铃声的URI。 String LAST_TIME_CONTACTED 上次与联系人联系的时间。 String PINNED 触点被固定的位置。 String SEND_TO_VOICEMAIL 是否应始终将联系人发送到语音邮件。 String STARRED 该联系人是否已主演？ 类型：INTEGER（布尔值） String TIMES_CONTACTED 联系人联系的次数 类型：INTEGER
From interface android.provider.ContactsContract.ContactNameColumns String DISPLAY_NAME_ALTERNATIVE 显示名称的替代表示，例如“姓氏优先”，而不是“西方名字的第一个名字”。 String DISPLAY_NAME_PRIMARY 基于联系人的最佳可用信息（例如，如果名称不可用，可能是电子邮件地址），显示标准文本作为联系人的显示名称。 String DISPLAY_NAME_SOURCE 用作联系人显示名称的数据种类，如结构化名称或电子邮件地址。 String PHONETIC_NAME 由 PHONETIC_NAME_STYLE指定的拼音字母中的全名的发音。 String PHONETIC_NAME_STYLE 用于表示 PHONETIC_NAME的拼音字母。 String SORT_KEY_ALTERNATIVE 根据全名的替代表示排序键， DISPLAY_NAME_ALTERNATIVE 。 String SORT_KEY_PRIMARY 排序键考虑了基于地区的传统，用于在地址簿中对姓名进行排序。
From interface android.provider.ContactsContract.SyncColumns String ACCOUNT_NAME 此行所属的帐户实例的名称，与 ACCOUNT_TYPE配对时标识特定帐户。 String ACCOUNT_TYPE 此行所属的帐户类型，当与 ACCOUNT_NAME配对时 ACCOUNT_NAME标识特定帐户。 String DIRTY 指示 VERSION已更改的标志，并且此行需要通过其拥有的帐户进行同步。 String SOURCE_ID 将此行唯一标识为其源帐户的字符串。 String VERSION 每当此行或其相关数据更改时更新的版本号。
From interface android.provider.ContactsContract.BaseSyncColumns String SYNC1 同步适配器使用的通用列。 String SYNC2 同步适配器使用的通用列。 String SYNC3 同步适配器使用的通用列。 String SYNC4 同步适配器使用的通用列。

Inherited methods

From class java.lang.Object Object clone() 创建并返回此对象的副本。 boolean equals(Object obj) 指示其他某个对象是否“等于”这一个。 void finalize() 当垃圾收集确定没有更多对该对象的引用时，由对象上的垃圾回收器调用。 final Class<?> getClass() 返回此 Object的运行时类。 int hashCode() 返回对象的哈希码值。 final void notify() 唤醒正在等待该对象监视器的单个线程。 final void notifyAll() 唤醒在该对象监视器上等待的所有线程。 String toString() 返回对象的字符串表示形式。 final void wait(long millis, int nanos) 导致当前线程等待，直到另一个线程为此对象调用方法 notify()或 notifyAll()方法，或者其他某个线程中断当前线程，或者经过一定的实时时间。 final void wait(long millis) 导致当前线程等待，直到另一个线程调用此对象的 notify()方法或 notifyAll()方法或经过了指定的时间量。 final void wait() 使当前线程等待，直到另一个线程调用此对象的方法 notify()或方法 notifyAll() 。

Constants

int AGGREGATION_MODE_DEFAULT

int AGGREGATION_MODE_DISABLED

int AGGREGATION_MODE_IMMEDIATE

int AGGREGATION_MODE_SUSPENDED

String CONTENT_ITEM_TYPE

String CONTENT_TYPE

Fields

Uri CONTENT_URI

Public methods

Uri getContactLookupUri (ContentResolver resolver, 
                Uri rawContactUri)

EntityIterator newEntityIterator (Cursor cursor)