联系人提供程序

联系人提供程序是一个功能强大且灵活的 Android 组件,它管理着设备的中央人员数据仓库。联系人提供程序是您在设备联系人应用中看到的数据来源,您也可以在自己的应用中访问其数据,并在设备和在线服务之间传输数据。该提供程序可兼容各种数据源,并尝试为每个人管理尽可能多的数据,因此其组织结构较为复杂。正因如此,该提供程序的 API 包含一组广泛的契约类和接口,可简化数据的检索和修改。

本指南介绍了以下内容

  • 基本的提供程序结构。
  • 如何从提供程序中检索数据。
  • 如何修改提供程序中的数据。
  • 如何编写用于将服务器数据同步到联系人提供程序的同步适配器。

本指南假设您了解 Android 内容提供程序的基础知识。要详细了解 Android 内容提供程序,请阅读内容提供程序基础知识指南。

联系人提供程序组织结构

联系人提供程序是一个 Android 内容提供程序组件。它维护关于个人的三种类型的数据,每种数据都对应于该提供程序提供的表格,如图 1 所示

图 1. 联系人提供程序表格结构。

这三个表格通常通过其契约类的名称来引用。这些类定义了这些表格使用的内容 URI、列名和列值的常量

ContactsContract.Contacts
表示不同人员的行,基于原始联系人行的聚合。
ContactsContract.RawContacts
包含个人数据摘要的行,特定于用户账号和类型。
ContactsContract.Data
包含原始联系人详细信息的行,例如电子邮件地址或电话号码。

ContactsContract 中的契约类表示的其他表是辅助表,联系人提供程序使用它们来管理其操作或支持设备联系人或电话应用中的特定功能。

原始联系人

原始联系人表示来自单一账号类型和账号名称的个人数据。由于联系人提供程序允许使用多个在线服务作为个人数据来源,因此它允许同一个人有多个原始联系人。多个原始联系人也允许用户合并同一账号类型中多个账号的个人数据。

原始联系人的大多数数据不存储在其 ContactsContract.RawContacts 表中的行中。相反,它存储在 ContactsContract.Data 表中的一行或多行中。每个数据行都有一列 Data.RAW_CONTACT_ID,其中包含其父级 ContactsContract.RawContacts 行的 RawContacts._ID 值。

重要原始联系人列

ContactsContract.RawContacts 表中的重要列如表 1 所示。请阅读表格后面的说明。

表 1. 重要原始联系人列。

列名称 用途 注意
ACCOUNT_NAME 此原始联系人来源的账号类型的账号名称。例如,Google 账号的账号名称是设备所有者的某个 Gmail 地址。有关详情,请参阅下一项 ACCOUNT_TYPE 此名称的格式取决于其账号类型。它不一定是电子邮件地址。
ACCOUNT_TYPE 此原始联系人来源的账号类型。例如,Google 账号的账号类型是 com.google。始终使用您拥有或控制的域的域标识符限定您的账号类型。这将确保您的账号类型是唯一的。 提供联系人数据的账号类型通常有一个关联的同步适配器,该适配器与联系人提供程序同步。
DELETED 原始联系人的“已删除”标志。 此标志允许联系人提供程序在内部维护该行,直到同步适配器能够从其服务器中删除该行,然后最终从仓库中删除该行。

注意

以下是关于 ContactsContract.RawContacts 表的重要说明

  • 原始联系人的姓名不存储在其 ContactsContract.RawContacts 表中的行中。相反,它存储在 ContactsContract.Data 表中的 ContactsContract.CommonDataKinds.StructuredName 行中。原始联系人在 ContactsContract.Data 表中只有一行此类数据。
  • 注意:要在原始联系人行中使用您自己的账号数据,必须首先向 AccountManager 注册。为此,请提示用户将其账号类型和账号名称添加到账号列表中。如果您不这样做,联系人提供程序将自动删除您的原始联系人行。

    例如,如果您希望您的应用为域名为 com.example.dataservice 的网络服务维护联系人数据,并且用户在该服务上的账号为 becky.sharp@dataservice.example.com,则用户必须先添加账号“类型”(com.example.dataservice)和账号“名称”(becky.smart@dataservice.example.com),然后您的应用才能添加原始联系人行。您可以在文档中向用户解释此要求,或者可以提示用户添加类型和名称,或者两者兼而有之。下一节将更详细地介绍账号类型和账号名称。

原始联系人数据来源

为了理解原始联系人的工作原理,请考虑用户“Emily Dickinson”,她在设备上定义了以下三个用户账号

  • emily.dickinson@gmail.com
  • emilyd@gmail.com
  • Twitter 账号“belle_of_amherst”

该用户已在“账号”设置中为这三个账号都启用了同步联系人

假设 Emily Dickinson 打开浏览器窗口,以 emily.dickinson@gmail.com 登录 Gmail,打开“联系人”,然后添加了“Thomas Higginson”。之后,她又以 emilyd@gmail.com 登录 Gmail,向“Thomas Higginson”发送了一封电子邮件,这会自动将他添加为联系人。她还在 Twitter 上关注了“colonel_tom”(Thomas Higginson 的 Twitter ID)。

因此,联系人提供程序创建了三个原始联系人

  1. emily.dickinson@gmail.com 相关联的“Thomas Higginson”的原始联系人。用户账号类型为 Google。
  2. emilyd@gmail.com 相关联的“Thomas Higginson”的第二个原始联系人。用户账号类型也是 Google。即使姓名与之前的姓名相同,但由于该联系人是为其他用户账号添加的,因此会有一个新的原始联系人。
  3. 与“belle_of_amherst”相关联的“Thomas Higginson”的第三个原始联系人。用户账号类型为 Twitter。

数据

如前所述,原始联系人的数据存储在与其 _ID 值关联的 ContactsContract.Data 行中。这使得一个原始联系人可以拥有同一类型数据的多个实例,例如电子邮件地址或电话号码。例如,如果 emilyd@gmail.com 的“Thomas Higginson”(与 Google 账号 emilyd@gmail.com 关联的 Thomas Higginson 的原始联系人行)的家庭电子邮件地址为 thigg@gmail.com,工作电子邮件地址为 thomas.higginson@gmail.com,则联系人提供程序会存储这两个电子邮件地址行,并将它们都链接到原始联系人。

请注意,不同类型的数据都存储在同一个表中。显示名称、电话号码、电子邮件、邮政地址、照片和网站详细信息行都可以在 ContactsContract.Data 表中找到。为了便于管理,ContactsContract.Data 表中有一些描述性名称的列,还有一些通用名称的列。描述性名称列的内容无论行中数据类型如何都具有相同的含义,而通用名称列的内容则根据数据类型具有不同的含义。

描述性列名称

一些描述性列名称的示例如下

RAW_CONTACT_ID
此数据的原始联系人的 _ID 列的值。
MIMETYPE
此行中存储的数据类型,表示为自定义 MIME 类型。联系人提供程序使用 ContactsContract.CommonDataKinds 子类中定义的 MIME 类型。这些 MIME 类型是开源的,可供任何使用联系人提供程序的应用或同步适配器使用。
IS_PRIMARY
如果原始联系人可以多次出现此类型的数据行,则 IS_PRIMARY 列会标记包含该类型主数据的数据行。例如,如果用户长按联系人的电话号码并选择设为默认,则包含该号码的 ContactsContract.Data 行的 IS_PRIMARY 列将被设置为非零值。

通用列名称

有 15 个通用列,命名为 DATA1DATA15,它们通常可用;另有四个通用列 SYNC1SYNC4,仅供同步适配器使用。无论行中包含的数据类型如何,通用列名称常量始终有效。

DATA1 列已编入索引。联系人提供程序始终使用此列存储提供程序预计将成为最常见查询目标的数据。例如,在电子邮件行中,此列包含实际的电子邮件地址。

按照惯例,列 DATA15 保留用于存储 Binary Large Object (BLOB) 数据,例如照片缩略图。

特定于类型的列名称

为了便于处理特定类型的行中的列,联系人提供程序还提供了特定于类型的列名称常量,这些常量在 ContactsContract.CommonDataKinds 的子类中定义。这些常量只是为同一列名称提供了不同的常量名称,这有助于您访问特定类型行中的数据。

例如,ContactsContract.CommonDataKinds.Email 类定义了 MIME 类型为 Email.CONTENT_ITEM_TYPEContactsContract.Data 行的特定于类型的列名称常量。该类包含电子邮件地址列的常量 ADDRESSADDRESS 的实际值是“data1”,这与该列的通用名称相同。

注意:不要使用具有提供程序预定义 MIME 类型的行向 ContactsContract.Data 表添加您自己的自定义数据。如果这样做,您可能会丢失数据或导致提供程序出现故障。例如,您不应添加 MIME 类型为 Email.CONTENT_ITEM_TYPE 且在 DATA1 列中包含用户名而非电子邮件地址的行。如果您为该行使用自己的自定义 MIME 类型,则可以自由定义自己的特定于类型的列名称并随意使用这些列。

图 2 显示了描述性列和数据列在 ContactsContract.Data 行中如何显示,以及特定于类型的列名称如何“覆盖”通用列名称

How type-specific column names map to generic column names

图 2. 特定于类型的列名称和通用列名称。

特定于类型的列名称类

表 2 列出了最常用的特定于类型的列名称类

表 2. 特定于类型的列名称类

映射类 数据类型 注意
ContactsContract.CommonDataKinds.StructuredName 与此数据行相关联的原始联系人的姓名数据。 原始联系人只有一行此类数据。
ContactsContract.CommonDataKinds.Photo 与此数据行相关联的原始联系人的主要照片。 原始联系人只有一行此类数据。
ContactsContract.CommonDataKinds.Email 与此数据行相关联的原始联系人的电子邮件地址。 一个原始联系人可以有多个电子邮件地址。
ContactsContract.CommonDataKinds.StructuredPostal 与此数据行相关联的原始联系人的邮政地址。 一个原始联系人可以有多个邮政地址。
ContactsContract.CommonDataKinds.GroupMembership 将原始联系人链接到联系人提供程序中某个组的标识符。 群组是账号类型和账号名称的可选功能。有关详细信息,请参阅联系人群组部分。

联系人

联系人提供程序将所有账号类型和账号名称的原始联系人行组合起来,形成一个联系人。这有助于显示和修改用户为某人收集的所有数据。联系人提供程序管理新联系人行的创建以及将原始联系人聚合到现有联系人行中。应用和同步适配器均不允许添加联系人,并且联系人行中的某些列是只读的。

注意:如果您尝试使用 insert() 向联系人提供程序添加联系人,您将收到 UnsupportedOperationException 异常。如果您尝试更新列为“只读”的列,则更新将被忽略。

联系人提供程序会在添加与任何现有联系人不匹配的新原始联系人时创建新联系人。如果现有原始联系人的数据发生变化,使其不再与之前关联的联系人匹配,提供程序也会这样做。如果应用或同步适配器创建了一个确实与现有联系人匹配的新原始联系人,则新原始联系人将聚合到现有联系人中。

联系人提供程序使用 Contacts 表中联系人行的 _ID 列将其联系人行链接到其原始联系人行。ContactsContract.RawContacts 原始联系人表的 CONTACT_ID 列包含与每个原始联系人行关联的联系人行的 _ID 值。

ContactsContract.Contacts 表还包含列 LOOKUP_KEY,它是指向联系人行的“永久”链接。由于联系人提供程序自动维护联系人,它可能会因聚合或同步而更改联系人行的 _ID 值。即使发生这种情况,内容 URI CONTENT_LOOKUP_URI 与联系人的 LOOKUP_KEY 组合仍将指向联系人行,因此您可以使用 LOOKUP_KEY 维护指向“收藏”联系人等的链接。此列有其自己的格式,与 _ID 列的格式无关。

图 3 显示了三个主要表之间的关系。

Contacts provider main tables

图 3. 联系人、原始联系人和详细信息表的关联关系。

注意:如果您将应用发布到 Google Play 商店,或者您的应用在运行 Android 10(API 级别 29)或更高版本的设备上运行,请记住,有限数量的联系人数据字段和方法已过时。

在上述条件下,系统会定期清除写入以下数据字段的任何值

用于设置上述数据字段的 API 也已过时

此外,以下字段不再返回常用联系人。请注意,其中某些字段仅在联系人属于特定的数据类型时才会影响联系人排名。

如果您的应用正在访问或更新这些字段或 API,请使用替代方法。例如,您可以通过使用私有内容提供程序或存储在您的应用或后端系统中的其他数据来实现某些用例。

要验证您的应用功能是否未受此更改影响,您可以手动清除这些数据字段。为此,请在运行 Android 4.1(API 级别 16)或更高版本的设备上运行以下 ADB 命令

adb shell content delete \
--uri content://com.android.contacts/contacts/delete_usage

来自同步适配器的数据

用户直接在设备中输入联系人数据,但数据也会通过同步适配器从 Web 服务流入联系人提供程序,这些同步适配器自动完成设备与服务之间的数据传输。同步适配器在系统控制下在后台运行,并调用 ContentResolver 方法来管理数据。

在 Android 中,同步适配器所使用的 Web 服务通过账号类型标识。每个同步适配器处理一种账号类型,但可以支持该类型的多个账号名称。账号类型和账号名称在原始联系人数据来源部分进行了简要描述。以下定义提供了更多详细信息,并描述了账号类型和名称与同步适配器及服务之间的关系。

账号类型
标识用户存储数据的服务。大多数情况下,用户必须向服务进行身份验证。例如,Google Contacts 是一种账号类型,由代码 google.com 标识。此值对应于 AccountManager 使用的账号类型。
账号名称
标识账号类型的特定账号或登录名。Google Contacts 账号与 Google 账号相同,后者使用电子邮件地址作为账号名称。其他服务可能使用单个词的用户名或数字 ID。

账号类型不必是唯一的。用户可以配置多个 Google Contacts 账号并将其数据下载到联系人提供程序;如果用户有一个个人账号名称的个人联系人集,以及一个工作账号的另一个联系人集,就可能会发生这种情况。账号名称通常是唯一的。它们共同标识联系人提供程序和外部服务之间的特定数据流。

如果您想将服务数据传输到联系人提供程序,您需要编写自己的同步适配器。这在联系人提供程序同步适配器部分有更详细的描述。

图 4 显示了联系人提供程序在关于人员的数据流中的位置。在标记为“同步适配器”的框中,每个适配器都标有其账号类型。

Flow of data about people

图 4. 联系人提供程序数据流。

所需权限

希望访问联系人提供程序的应用必须请求以下权限

读取一个或多个表格的权限
READ_CONTACTS,在 AndroidManifest.xml 中使用 <uses-permission> 元素指定为 <uses-permission android:name="android.permission.READ_CONTACTS">
写入一个或多个表格的权限
WRITE_CONTACTS,在 AndroidManifest.xml 中使用 <uses-permission> 元素指定为 <uses-permission android:name="android.permission.WRITE_CONTACTS">

这些权限不适用于用户个人资料数据。用户个人资料及其所需权限将在下一节用户个人资料中讨论。

请记住,用户的联系人数据是个人敏感数据。用户关心自己的隐私,因此不希望应用收集有关他们或其联系人的数据。如果您需要访问其联系人数据的理由不明确,他们可能会给您的应用较低的评分或直接拒绝安装。

用户个人资料

ContactsContract.Contacts 表中有一个包含设备用户的个人资料数据的单行。此数据描述设备的 user,而不是用户的联系人之一。个人资料联系人行链接到使用个人资料的每个系统的原始联系人行。每个个人资料原始联系人行可以有多行数据。用于访问用户个人资料的常量可在 ContactsContract.Profile 类中找到。

访问用户个人资料需要特殊权限。除了读取和写入所需的 READ_CONTACTSWRITE_CONTACTS 权限外,访问用户个人资料分别需要 android.Manifest.permission#READ_PROFILE 和 android.Manifest.permission#WRITE_PROFILE 权限来进行读取和写入。

请记住,您应将用户个人资料视为敏感信息。权限 android.Manifest.permission#READ_PROFILE 允许您访问设备用户的个人身份信息。请确保在应用说明中告知用户您为何需要用户个人资料访问权限。

要检索包含用户个人资料的联系人行,请调用 ContentResolver.query()。将内容 URI 设置为 CONTENT_URI,并且不提供任何选择条件。您也可以使用此内容 URI 作为检索原始联系人或个人资料数据的基本 URI。例如,以下代码段检索个人资料数据。

Kotlin

// Sets the columns to retrieve for the user profile
projection = arrayOf(
        ContactsContract.Profile._ID,
        ContactsContract.Profile.DISPLAY_NAME_PRIMARY,
        ContactsContract.Profile.LOOKUP_KEY,
        ContactsContract.Profile.PHOTO_THUMBNAIL_URI
)

// Retrieves the profile from the Contacts Provider
profileCursor = contentResolver.query(
        ContactsContract.Profile.CONTENT_URI,
        projection,
        null,
        null,
        null
)

Java

// Sets the columns to retrieve for the user profile
projection = new String[]
    {
        Profile._ID,
        Profile.DISPLAY_NAME_PRIMARY,
        Profile.LOOKUP_KEY,
        Profile.PHOTO_THUMBNAIL_URI
    };

// Retrieves the profile from the Contacts Provider
profileCursor =
        getContentResolver().query(
                Profile.CONTENT_URI,
                projection ,
                null,
                null,
                null);

注意:如果您检索了多行联系人,并且想确定其中一行是否为用户个人资料,请测试该行的 IS_USER_PROFILE 列。如果联系人是用户个人资料,此列将设置为“1”。

联系人提供程序元数据

联系人提供程序管理用于跟踪仓库中联系人数据状态的数据。此关于仓库的元数据存储在各种位置,包括 Raw Contacts、Data 和 Contacts 表格行、ContactsContract.Settings 表格以及 ContactsContract.SyncState 表格。下表显示了这些元数据的每个部分的效应。

表 3. 联系人提供程序中的元数据

表格 含义
ContactsContract.RawContacts DIRTY “0” - 自上次同步以来未更改。 标记在设备上已更改且必须同步回服务器的原始联系人。当 Android 应用更新行时,此值由联系人提供程序自动设置。

修改原始联系人或数据表的同步适配器应始终将字符串 CALLER_IS_SYNCADAPTER 附加到其使用的内容 URI 中。这可以防止提供程序将行标记为脏数据。否则,同步适配器的修改将显示为本地修改并发送到服务器,即使服务器是修改的来源。

“1” - 自上次同步以来已更改,需要同步回服务器。
ContactsContract.RawContacts VERSION 此行的版本号。 每当该行或其相关数据发生变化时,联系人提供程序会自动增加此值。
ContactsContract.Data DATA_VERSION 此行的版本号。 每当数据行更改时,联系人提供程序会自动增加此值。
ContactsContract.RawContacts SOURCE_ID 在创建此原始联系人的账号中唯一标识此原始联系人的字符串值。 当同步适配器创建新的原始联系人时,此列应设置为服务器用于该原始联系人的唯一 ID。当 Android 应用创建新的原始联系人时,应用应将此列留空。这会向同步适配器发出信号,表示它应该在服务器上创建新的原始联系人,并获取 SOURCE_ID 的值。

特别是,源 ID 对于每种账号类型都必须是唯一的,并且在同步之间应保持稳定

  • 唯一:每个账号的原始联系人都必须有其自己的源 ID。如果您不强制执行此规定,将在联系人应用中导致问题。请注意,同一账号类型的两个原始联系人可能具有相同的源 ID。例如,账号 emily.dickinson@gmail.com 的原始联系人“Thomas Higginson”允许与账号 emilyd@gmail.com 的原始联系人“Thomas Higginson”具有相同的源 ID。
  • 稳定:源 ID 是在线服务中关于原始联系人数据的永久组成部分。例如,如果用户在应用设置中清除“联系人存储”并重新同步,恢复的原始联系人应具有与之前相同的源 ID。如果您不强制执行此规定,快捷方式将停止工作。
ContactsContract.Groups GROUP_VISIBLE “0” - 此群组中的联系人不应在 Android 应用界面中显示。 此列用于与允许用户隐藏某些群组中联系人的服务器兼容。
“1” - 此群组中的联系人允许在应用界面中显示。
ContactsContract.Settings UNGROUPED_VISIBLE “0” - 对于此账号和账号类型,不属于任何群组的联系人在 Android 应用界面中不可见。 默认情况下,如果原始联系人都不属于任何群组,则联系人不可见(原始联系人的群组成员身份由 ContactsContract.Data 表中的一行或多行 ContactsContract.CommonDataKinds.GroupMembership 指示)。通过在账号类型和账号的 ContactsContract.Settings 表格行中设置此标志,您可以强制使不属于群组的联系人可见。此标志的一个用途是显示来自不使用群组的服务器的联系人。
“1” - 对于此账号和账号类型,不属于任何群组的联系人在应用界面中可见。
ContactsContract.SyncState (全部) 使用此表格存储同步适配器的元数据。 使用此表格,您可以在设备上持久存储同步状态和其他同步相关数据。

联系人提供程序访问

本节描述了从联系人提供程序访问数据的指南,重点关注以下方面

  • 实体查询。
  • 批量修改。
  • 使用 Intent 检索和修改。
  • 数据完整性。

从同步适配器进行修改也将在联系人提供程序同步适配器部分中更详细地介绍。

查询实体

由于联系人提供程序表格以分层结构组织,通常检索一行及其所有链接的“子”行很有用。例如,要显示一个人的所有信息,您可能需要检索单个 ContactsContract.Contacts 行对应的所有 ContactsContract.RawContacts 行,或者单个 ContactsContract.RawContacts 行对应的所有 ContactsContract.CommonDataKinds.Email 行。为了便于实现这一点,联系人提供程序提供了充当表格之间数据库连接的实体结构。

实体就像一个由父表及其子表中选定列组成的表。当您查询实体时,您会根据实体中可用的列提供一个 Projection 和搜索条件。结果是一个 Cursor,其中包含检索到的每个子表行的一行。例如,如果您查询 ContactsContract.Contacts.Entity 以获取联系人姓名以及该姓名所有原始联系人的所有 ContactsContract.CommonDataKinds.Email 行,您将获得一个包含每个 ContactsContract.CommonDataKinds.Email 行的 Cursor

实体简化了查询。使用实体,您可以一次检索联系人或原始联系人的所有联系人数据,而无需先查询父表获取 ID,然后再使用该 ID 查询子表。此外,联系人提供程序在单个事务中处理针对实体的查询,这确保了检索到的数据内部一致。

注意:实体通常不包含父表和子表的所有列。如果您尝试使用实体列名称常量列表中不存在的列名称,您将收到 Exception

以下代码段显示了如何检索联系人的所有原始联系人行。该代码段是包含两个 Activity(“main”和“detail”)的更大应用的一部分。“main”Activity 显示联系人行列表;当用户选择其中一个时,Activity 会将其 ID 发送给“detail”Activity。“detail”Activity 使用 ContactsContract.Contacts.Entity 显示与所选联系人相关联的所有原始联系人的所有数据行。

此代码段取自“detail”Activity

Kotlin

...
    /*
     * Appends the entity path to the URI. In the case of the Contacts Provider, the
     * expected URI is content://com.google.contacts/#/entity (# is the ID value).
     */
    contactUri = Uri.withAppendedPath(
            contactUri,
            ContactsContract.Contacts.Entity.CONTENT_DIRECTORY
    )

    // Initializes the loader identified by LOADER_ID.
    loaderManager.initLoader(
            LOADER_ID,  // The identifier of the loader to initialize
            null,       // Arguments for the loader (in this case, none)
            this        // The context of the activity
    )

    // Creates a new cursor adapter to attach to the list view
    cursorAdapter = SimpleCursorAdapter(
            this,                       // the context of the activity
            R.layout.detail_list_item,  // the view item containing the detail widgets
            mCursor,                    // the backing cursor
            fromColumns,               // the columns in the cursor that provide the data
            toViews,                   // the views in the view item that display the data
            0)                          // flags

    // Sets the ListView's backing adapter.
    rawContactList.adapter = cursorAdapter
...
override fun onCreateLoader(id: Int, args: Bundle?): Loader<Cursor> {
    /*
     * Sets the columns to retrieve.
     * RAW_CONTACT_ID is included to identify the raw contact associated with the data row.
     * DATA1 contains the first column in the data row (usually the most important one).
     * MIMETYPE indicates the type of data in the data row.
     */
    val projection: Array<String> = arrayOf(
            ContactsContract.Contacts.Entity.RAW_CONTACT_ID,
            ContactsContract.Contacts.Entity.DATA1,
            ContactsContract.Contacts.Entity.MIMETYPE
    )

    /*
     * Sorts the retrieved cursor by raw contact id, to keep all data rows for a single raw
     * contact collated together.
     */
    val sortOrder = "${ContactsContract.Contacts.Entity.RAW_CONTACT_ID} ASC"

    /*
     * Returns a new CursorLoader. The arguments are similar to
     * ContentResolver.query(), except for the Context argument, which supplies the location of
     * the ContentResolver to use.
     */
    return CursorLoader(
            applicationContext, // The activity's context
            contactUri,        // The entity content URI for a single contact
            projection,         // The columns to retrieve
            null,               // Retrieve all the raw contacts and their data rows.
            null,               //
            sortOrder           // Sort by the raw contact ID.
    )
}

Java

...
    /*
     * Appends the entity path to the URI. In the case of the Contacts Provider, the
     * expected URI is content://com.google.contacts/#/entity (# is the ID value).
     */
    contactUri = Uri.withAppendedPath(
            contactUri,
            ContactsContract.Contacts.Entity.CONTENT_DIRECTORY);

    // Initializes the loader identified by LOADER_ID.
    getLoaderManager().initLoader(
            LOADER_ID,  // The identifier of the loader to initialize
            null,       // Arguments for the loader (in this case, none)
            this);      // The context of the activity

    // Creates a new cursor adapter to attach to the list view
    cursorAdapter = new SimpleCursorAdapter(
            this,                        // the context of the activity
            R.layout.detail_list_item,   // the view item containing the detail widgets
            mCursor,                     // the backing cursor
            fromColumns,                // the columns in the cursor that provide the data
            toViews,                    // the views in the view item that display the data
            0);                          // flags

    // Sets the ListView's backing adapter.
    rawContactList.setAdapter(cursorAdapter);
...
@Override
public Loader<Cursor> onCreateLoader(int id, Bundle args) {

    /*
     * Sets the columns to retrieve.
     * RAW_CONTACT_ID is included to identify the raw contact associated with the data row.
     * DATA1 contains the first column in the data row (usually the most important one).
     * MIMETYPE indicates the type of data in the data row.
     */
    String[] projection =
        {
            ContactsContract.Contacts.Entity.RAW_CONTACT_ID,
            ContactsContract.Contacts.Entity.DATA1,
            ContactsContract.Contacts.Entity.MIMETYPE
        };

    /*
     * Sorts the retrieved cursor by raw contact id, to keep all data rows for a single raw
     * contact collated together.
     */
    String sortOrder =
            ContactsContract.Contacts.Entity.RAW_CONTACT_ID +
            " ASC";

    /*
     * Returns a new CursorLoader. The arguments are similar to
     * ContentResolver.query(), except for the Context argument, which supplies the location of
     * the ContentResolver to use.
     */
    return new CursorLoader(
            getApplicationContext(),  // The activity's context
            contactUri,              // The entity content URI for a single contact
            projection,               // The columns to retrieve
            null,                     // Retrieve all the raw contacts and their data rows.
            null,                     //
            sortOrder);               // Sort by the raw contact ID.
}

加载完成后,LoaderManager 调用回调到 onLoadFinished()。此方法的传入参数之一是包含查询结果的 Cursor。在您自己的应用中,您可以从此 Cursor 中获取数据以显示或进一步处理。

批量修改

尽可能地,您应该以“批量模式”在联系人提供程序中插入、更新和删除数据,方法是创建 ArrayListContentProviderOperation 对象并调用 applyBatch()。由于联系人提供程序在单个事务中执行 applyBatch() 中的所有操作,因此您的修改永远不会使联系人仓库处于不一致的状态。批量修改还便于同时插入原始联系人及其详细信息数据。

注意:要修改单个原始联系人,请考虑向设备联系人应用发送 Intent,而不是在您的应用中处理修改。这在使用 Intent 检索和修改部分有更详细的描述。

让步点

包含大量操作的批量修改可能会阻塞其他进程,导致整体用户体验不佳。为了将您要执行的所有修改组织到尽可能少的单独列表中,同时防止它们阻塞系统,您应该为一个或多个操作设置让步点。让步点是指其 isYieldAllowed() 值设置为 trueContentProviderOperation 对象。当联系人提供程序遇到让步点时,它会暂停工作,让其他进程运行并结束当前事务。当提供程序再次启动时,它会继续处理 ArrayList 中的下一个操作并开始新的事务。

让步点确实会导致每次调用 applyBatch() 产生多个事务。因此,您应该为一组相关行的最后一个操作设置一个让步点。例如,您应该为添加原始联系人行及其关联数据行的操作集中的最后一个操作,或与单个联系人相关的一组行中的最后一个操作设置一个让步点。

让步点也是原子操作的单位。两次让步点之间的所有访问将作为一个整体成功或失败。如果您不设置任何让步点,最小的原子操作是整个批量操作。如果您使用让步点,则可以防止操作降低系统性能,同时确保操作子集是原子性的。

修改回溯引用

当您将新的原始联系人行及其关联的数据行作为一组 ContentProviderOperation 对象插入时,您必须通过将原始联系人的 _ID 值作为 RAW_CONTACT_ID 值插入,将数据行链接到原始联系人行。但是,当您为数据行创建 ContentProviderOperation 时,此值不可用,因为您尚未应用原始联系人行的 ContentProviderOperation。为了解决这个问题,ContentProviderOperation.Builder 类提供了 withValueBackReference() 方法。此方法允许您使用先前操作的结果插入或修改列。

withValueBackReference() 方法有两个参数

键值对中的键。此参数的值应该是您正在修改的表中列的名称。
previousResult
applyBatch() 返回的 ContentProviderResult 对象数组中某个值的基于 0 的索引。应用批量操作时,每个操作的结果都存储在中间结果数组中。previousResult 值是其中一个结果的索引,该结果被检索并与 key 值一起存储。这使您可以在插入新的原始联系人记录后获取其 _ID 值,然后在添加 ContactsContract.Data 行时对该值进行“回溯引用”。

调用 applyBatch() 时会创建完整的结果数组,其大小等于您提供的 ArrayListContentProviderOperation 对象的大小。但是,结果数组中的所有元素都设置为 null,如果您尝试回溯引用尚未应用的某个操作的结果,withValueBackReference() 会抛出 Exception

以下代码段展示了如何批量插入新的原始联系人及其数据。它们包含设置让步点并使用回溯引用的代码。

第一个代码段从 UI 中检索联系人数据。此时,用户已经选择了应该添加新原始联系人的账号。

Kotlin

// Creates a contact entry from the current UI values, using the currently-selected account.
private fun createContactEntry() {
    /*
     * Gets values from the UI
     */
    val name = contactNameEditText.text.toString()
    val phone = contactPhoneEditText.text.toString()
    val email = contactEmailEditText.text.toString()

    val phoneType: String = contactPhoneTypes[mContactPhoneTypeSpinner.selectedItemPosition]

    val emailType: String = contactEmailTypes[mContactEmailTypeSpinner.selectedItemPosition]

Java

// Creates a contact entry from the current UI values, using the currently-selected account.
protected void createContactEntry() {
    /*
     * Gets values from the UI
     */
    String name = contactNameEditText.getText().toString();
    String phone = contactPhoneEditText.getText().toString();
    String email = contactEmailEditText.getText().toString();

    int phoneType = contactPhoneTypes.get(
            contactPhoneTypeSpinner.getSelectedItemPosition());

    int emailType = contactEmailTypes.get(
            contactEmailTypeSpinner.getSelectedItemPosition());

下一个代码段创建操作以将原始联系人行插入 ContactsContract.RawContacts 表中

Kotlin

    /*
     * Prepares the batch operation for inserting a new raw contact and its data. Even if
     * the Contacts Provider does not have any data for this person, you can't add a Contact,
     * only a raw contact. The Contacts Provider will then add a Contact automatically.
     */

    // Creates a new array of ContentProviderOperation objects.
    val ops = arrayListOf<ContentProviderOperation>()

    /*
     * Creates a new raw contact with its account type (server type) and account name
     * (user's account). Remember that the display name is not stored in this row, but in a
     * StructuredName data row. No other data is required.
     */
    var op: ContentProviderOperation.Builder =
            ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI)
                    .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.name)
                    .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.type)

    // Builds the operation and adds it to the array of operations
    ops.add(op.build())

Java

    /*
     * Prepares the batch operation for inserting a new raw contact and its data. Even if
     * the Contacts Provider does not have any data for this person, you can't add a Contact,
     * only a raw contact. The Contacts Provider will then add a Contact automatically.
     */

     // Creates a new array of ContentProviderOperation objects.
    ArrayList<ContentProviderOperation> ops =
            new ArrayList<ContentProviderOperation>();

    /*
     * Creates a new raw contact with its account type (server type) and account name
     * (user's account). Remember that the display name is not stored in this row, but in a
     * StructuredName data row. No other data is required.
     */
    ContentProviderOperation.Builder op =
            ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI)
            .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.getType())
            .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.getName());

    // Builds the operation and adds it to the array of operations
    ops.add(op.build());

接下来,代码为显示名称、电话和电子邮件行创建数据行。

每个操作构建器对象都使用 withValueBackReference() 获取 RAW_CONTACT_ID。该引用指向第一个操作(添加原始联系人行并返回其新的 _ID 值)的 ContentProviderResult 对象。因此,每个数据行都通过其 RAW_CONTACT_ID 自动链接到其所属的新 ContactsContract.RawContacts 行。

添加电子邮件行的 ContentProviderOperation.Builder 对象使用 withYieldAllowed() 标记,这将设置一个让步点

Kotlin

    // Creates the display name for the new raw contact, as a StructuredName data row.
    op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            /*
             * withValueBackReference sets the value of the first argument to the value of
             * the ContentProviderResult indexed by the second argument. In this particular
             * call, the raw contact ID column of the StructuredName data row is set to the
             * value of the result returned by the first operation, which is the one that
             * actually adds the raw contact row.
             */
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)

            // Sets the data row's MIME type to StructuredName
            .withValue(ContactsContract.Data.MIMETYPE,
                    ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE)

            // Sets the data row's display name to the name in the UI.
            .withValue(ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME, name)

    // Builds the operation and adds it to the array of operations
    ops.add(op.build())

    // Inserts the specified phone number and type as a Phone data row
    op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            /*
             * Sets the value of the raw contact id column to the new raw contact ID returned
             * by the first operation in the batch.
             */
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)

            // Sets the data row's MIME type to Phone
            .withValue(ContactsContract.Data.MIMETYPE,
                    ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE)

            // Sets the phone number and type
            .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone)
            .withValue(ContactsContract.CommonDataKinds.Phone.TYPE, phoneType)

    // Builds the operation and adds it to the array of operations
    ops.add(op.build())

    // Inserts the specified email and type as a Phone data row
    op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            /*
             * Sets the value of the raw contact id column to the new raw contact ID returned
             * by the first operation in the batch.
             */
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)

            // Sets the data row's MIME type to Email
            .withValue(ContactsContract.Data.MIMETYPE,
                    ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE)

            // Sets the email address and type
            .withValue(ContactsContract.CommonDataKinds.Email.ADDRESS, email)
            .withValue(ContactsContract.CommonDataKinds.Email.TYPE, emailType)

    /*
     * Demonstrates a yield point. At the end of this insert, the batch operation's thread
     * will yield priority to other threads. Use after every set of operations that affect a
     * single contact, to avoid degrading performance.
     */
    op.withYieldAllowed(true)

    // Builds the operation and adds it to the array of operations
    ops.add(op.build())

Java

    // Creates the display name for the new raw contact, as a StructuredName data row.
    op =
            ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            /*
             * withValueBackReference sets the value of the first argument to the value of
             * the ContentProviderResult indexed by the second argument. In this particular
             * call, the raw contact ID column of the StructuredName data row is set to the
             * value of the result returned by the first operation, which is the one that
             * actually adds the raw contact row.
             */
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)

            // Sets the data row's MIME type to StructuredName
            .withValue(ContactsContract.Data.MIMETYPE,
                    ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE)

            // Sets the data row's display name to the name in the UI.
            .withValue(ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME, name);

    // Builds the operation and adds it to the array of operations
    ops.add(op.build());

    // Inserts the specified phone number and type as a Phone data row
    op =
            ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            /*
             * Sets the value of the raw contact id column to the new raw contact ID returned
             * by the first operation in the batch.
             */
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)

            // Sets the data row's MIME type to Phone
            .withValue(ContactsContract.Data.MIMETYPE,
                    ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE)

            // Sets the phone number and type
            .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone)
            .withValue(ContactsContract.CommonDataKinds.Phone.TYPE, phoneType);

    // Builds the operation and adds it to the array of operations
    ops.add(op.build());

    // Inserts the specified email and type as a Phone data row
    op =
            ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            /*
             * Sets the value of the raw contact id column to the new raw contact ID returned
             * by the first operation in the batch.
             */
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)

            // Sets the data row's MIME type to Email
            .withValue(ContactsContract.Data.MIMETYPE,
                    ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE)

            // Sets the email address and type
            .withValue(ContactsContract.CommonDataKinds.Email.ADDRESS, email)
            .withValue(ContactsContract.CommonDataKinds.Email.TYPE, emailType);

    /*
     * Demonstrates a yield point. At the end of this insert, the batch operation's thread
     * will yield priority to other threads. Use after every set of operations that affect a
     * single contact, to avoid degrading performance.
     */
    op.withYieldAllowed(true);

    // Builds the operation and adds it to the array of operations
    ops.add(op.build());

最后一个代码段显示了调用 applyBatch() 插入新原始联系人及其数据行的过程。

Kotlin

    // Ask the Contacts Provider to create a new contact
    Log.d(TAG, "Selected account: ${mSelectedAccount.name} (${mSelectedAccount.type})")
    Log.d(TAG, "Creating contact: $name")

    /*
     * Applies the array of ContentProviderOperation objects in batch. The results are
     * discarded.
     */
    try {
        contentResolver.applyBatch(ContactsContract.AUTHORITY, ops)
    } catch (e: Exception) {
        // Display a warning
        val txt: String = getString(R.string.contactCreationFailure)
        Toast.makeText(applicationContext, txt, Toast.LENGTH_SHORT).show()

        // Log exception
        Log.e(TAG, "Exception encountered while inserting contact: $e")
    }
}

Java

    // Ask the Contacts Provider to create a new contact
    Log.d(TAG,"Selected account: " + selectedAccount.getName() + " (" +
            selectedAccount.getType() + ")");
    Log.d(TAG,"Creating contact: " + name);

    /*
     * Applies the array of ContentProviderOperation objects in batch. The results are
     * discarded.
     */
    try {

            getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);
    } catch (Exception e) {

            // Display a warning
            Context ctx = getApplicationContext();

            CharSequence txt = getString(R.string.contactCreationFailure);
            int duration = Toast.LENGTH_SHORT;
            Toast toast = Toast.makeText(ctx, txt, duration);
            toast.show();

            // Log exception
            Log.e(TAG, "Exception encountered while inserting contact: " + e);
    }
}

批量操作还允许您实现乐观并发控制,这是一种在不必锁定底层仓库的情况下应用修改事务的方法。要使用此方法,您应用事务,然后检查可能同时进行的其他修改。如果您发现发生了不一致的修改,您会回滚事务并重试。

乐观并发控制对于移动设备非常有用,因为移动设备通常一次只有一个用户,同时访问数据仓库的情况很少见。由于不使用锁定,因此不会浪费时间来设置锁定或等待其他事务释放其锁定。

在更新单个 ContactsContract.RawContacts 行时使用乐观并发控制,请执行以下步骤

  1. 检索原始联系人的 VERSION 列以及您检索的其他数据。
  2. 使用 newAssertQuery(Uri) 方法创建一个适用于强制执行约束的 ContentProviderOperation.Builder 对象。对于内容 URI,请使用附加了原始联系人的 _IDRawContacts.CONTENT_URI
  3. 对于 ContentProviderOperation.Builder 对象,调用 withValue()VERSION 列与刚刚检索到的版本号进行比较。
  4. 对于同一个 ContentProviderOperation.Builder,调用 withExpectedCount() 以确保此断言仅测试一行。
  5. 调用 build() 创建 ContentProviderOperation 对象,然后将此对象作为传递给 applyBatch()ArrayList 中的第一个对象。
  6. 应用批量事务。

如果在您读取原始联系人行和尝试修改它之间,该行被其他操作更新,“断言”ContentProviderOperation 将失败,并且整个批量操作将被回滚。然后您可以选择重试该批处理或采取其他操作。

以下代码段演示了在使用 CursorLoader 查询单个原始联系人后如何创建“断言”ContentProviderOperation

Kotlin

/*
 * The application uses CursorLoader to query the raw contacts table. The system calls this method
 * when the load is finished.
 */
override fun onLoadFinished(loader: Loader<Cursor>, cursor: Cursor) {
    // Gets the raw contact's _ID and VERSION values
    rawContactID = cursor.getLong(cursor.getColumnIndex(BaseColumns._ID))
    mVersion = cursor.getInt(cursor.getColumnIndex(SyncColumns.VERSION))
}

...

// Sets up a Uri for the assert operation
val rawContactUri: Uri = ContentUris.withAppendedId(
        ContactsContract.RawContacts.CONTENT_URI,
        rawContactID
)

// Creates a builder for the assert operation
val assertOp: ContentProviderOperation.Builder =
        ContentProviderOperation.newAssertQuery(rawContactUri).apply {
            // Adds the assertions to the assert operation: checks the version
            withValue(SyncColumns.VERSION, mVersion)

            // and count of rows tested
            withExpectedCount(1)
        }

// Creates an ArrayList to hold the ContentProviderOperation objects
val ops = arrayListOf<ContentProviderOperation>()

ops.add(assertOp.build())

// You would add the rest of your batch operations to "ops" here

...

// Applies the batch. If the assert fails, an Exception is thrown
try {
    val results: Array<ContentProviderResult> = contentResolver.applyBatch(AUTHORITY, ops)
} catch (e: OperationApplicationException) {
    // Actions you want to take if the assert operation fails go here
}

Java

/*
 * The application uses CursorLoader to query the raw contacts table. The system calls this method
 * when the load is finished.
 */
public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) {

    // Gets the raw contact's _ID and VERSION values
    rawContactID = cursor.getLong(cursor.getColumnIndex(BaseColumns._ID));
    mVersion = cursor.getInt(cursor.getColumnIndex(SyncColumns.VERSION));
}

...

// Sets up a Uri for the assert operation
Uri rawContactUri = ContentUris.withAppendedId(RawContacts.CONTENT_URI, rawContactID);

// Creates a builder for the assert operation
ContentProviderOperation.Builder assertOp = ContentProviderOperation.newAssertQuery(rawContactUri);

// Adds the assertions to the assert operation: checks the version and count of rows tested
assertOp.withValue(SyncColumns.VERSION, mVersion);
assertOp.withExpectedCount(1);

// Creates an ArrayList to hold the ContentProviderOperation objects
ArrayList ops = new ArrayList<ContentProviderOperation>;

ops.add(assertOp.build());

// You would add the rest of your batch operations to "ops" here

...

// Applies the batch. If the assert fails, an Exception is thrown
try
    {
        ContentProviderResult[] results =
                getContentResolver().applyBatch(AUTHORITY, ops);

    } catch (OperationApplicationException e) {

        // Actions you want to take if the assert operation fails go here
    }

使用 Intent 检索和修改

向设备的联系人应用发送 Intent,您可以间接访问联系人提供程序。Intent 会启动设备的联系人应用 UI,用户可以在其中执行与联系人相关的操作。通过这种类型的访问,用户可以

  • 从列表中选择一个联系人,并将其返回到您的应用中进行进一步处理。
  • 编辑现有联系人的数据。
  • 为其任何账号插入新的原始联系人。
  • 删除联系人或联系人数据。

如果用户正在插入或更新数据,您可以先收集数据并将其作为 Intent 的一部分发送。

当您通过设备的联系人应用使用 Intent 访问联系人提供程序时,您无需编写自己的 UI 或访问提供程序的代码。您也无需请求读取或写入提供程序的权限。设备的联系人应用可以将联系人的读取权限委托给您,并且由于您是通过其他应用修改提供程序,因此您无需具备写入权限。

将 Intent 发送到访问提供程序的总体流程在内容提供程序基础知识指南的“通过 Intent 访问数据”部分有详细描述。可用任务使用的操作、MIME 类型和数据值总结在表 4 中,而可与 putExtra() 一起使用的 extras 值列在 ContactsContract.Intents.Insert 的参考文档中。

表 4. 联系人提供程序 Intent。

任务 操作 数据 MIME 类型 注意
从列表中选择联系人 ACTION_PICK 以下之一 未使用 显示原始联系人列表或原始联系人数据列表,具体取决于您提供的内容 URI 类型。

调用 startActivityForResult(),它返回所选行的内容 URI。该 URI 的形式是表的 Content URI 附加了该行的 LOOKUP_ID。设备的联系人应用在该 Activity 的生命周期内将该 Content URI 的读写权限委托给您。更多详细信息请参见内容提供程序基础知识指南。

插入新的原始联系人 Insert.ACTION 不适用 RawContacts.CONTENT_TYPE,一组原始联系人的 MIME 类型。 显示设备联系人应用的“添加联系人”屏幕。您添加到 Intent 中的 extras 值会显示出来。如果使用 startActivityForResult() 发送,新添加的原始联系人的内容 URI 将在 Intent 参数的“data”字段中传递回您 Activity 的 onActivityResult() 回调方法。要获取该值,请调用 getData()
编辑联系人 CONTENT_LOOKUP_URI,用于该联系人。编辑器 Activity 将允许用户编辑与此联系人相关的任何数据。 Contacts.CONTENT_ITEM_TYPE,单个联系人。 在联系人应用中显示“编辑联系人”屏幕。您添加到 Intent 中的 extras 值会显示出来。当用户点击完成保存编辑时,您的 Activity 会返回前台。 显示一个也可以添加数据的选择器。
ACTION_INSERT_OR_EDIT CONTENT_ITEM_TYPE 不适用 此 Intent 始终显示联系人应用的选择器屏幕。用户可以选择联系人进行编辑,或者添加新联系人。根据用户的选择,会显示编辑或添加屏幕,并且您在 Intent 中传递的 extras 数据会显示出来。如果您的应用显示联系人数据(例如电子邮件或电话号码),请使用此 Intent 允许用户将数据添加到现有联系人中。 注意:在此 Intent 的 extras 中无需发送姓名值,因为用户始终选择现有姓名或添加新姓名。此外,如果您发送姓名,并且用户选择进行编辑,联系人应用将显示您发送的姓名,覆盖之前的值。如果用户没有注意到这一点并保存编辑,则旧值将丢失。

设备的联系人应用不允许您使用 Intent 删除原始联系人或其任何数据。相反,要删除原始联系人,请使用 ContentResolver.delete()ContentProviderOperation.newDelete()

以下代码段显示了如何构建和发送插入新的原始联系人及其数据的 Intent

数据完整性

Kotlin

// Gets values from the UI
val name = contactNameEditText.text.toString()
val phone = contactPhoneEditText.text.toString()
val email = contactEmailEditText.text.toString()

val company = companyName.text.toString()
val jobtitle = jobTitle.text.toString()

/*
 * Demonstrates adding data rows as an array list associated with the DATA key
 */

// Defines an array list to contain the ContentValues objects for each row
val contactData = arrayListOf<ContentValues>()

/*
 * Defines the raw contact row
 */

// Sets up the row as a ContentValues object
val rawContactRow = ContentValues().apply {
    // Adds the account type and name to the row
    put(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.type)
    put(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.name)
}

// Adds the row to the array
contactData.add(rawContactRow)

/*
 * Sets up the phone number data row
 */

// Sets up the row as a ContentValues object
val phoneRow = ContentValues().apply {
    // Specifies the MIME type for this data row (all data rows must be marked by their type)
    put(ContactsContract.Data.MIMETYPE,ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE)

    // Adds the phone number and its type to the row
    put(ContactsContract.CommonDataKinds.Phone.NUMBER, phone)
}

// Adds the row to the array
contactData.add(phoneRow)

/*
 * Sets up the email data row
 */

// Sets up the row as a ContentValues object
val emailRow = ContentValues().apply {
    // Specifies the MIME type for this data row (all data rows must be marked by their type)
    put(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE)

    // Adds the email address and its type to the row
    put(ContactsContract.CommonDataKinds.Email.ADDRESS, email)
}

// Adds the row to the array
contactData.add(emailRow)

// Creates a new intent for sending to the device's contacts application
val insertIntent = Intent(ContactsContract.Intents.Insert.ACTION).apply {
    // Sets the MIME type to the one expected by the insertion activity
    type = ContactsContract.RawContacts.CONTENT_TYPE

    // Sets the new contact name
    putExtra(ContactsContract.Intents.Insert.NAME, name)

    // Sets the new company and job title
    putExtra(ContactsContract.Intents.Insert.COMPANY, company)
    putExtra(ContactsContract.Intents.Insert.JOB_TITLE, jobtitle)

    /*
    * Adds the array to the intent's extras. It must be a parcelable object in order to
    * travel between processes. The device's contacts app expects its key to be
    * Intents.Insert.DATA
    */
    putParcelableArrayListExtra(ContactsContract.Intents.Insert.DATA, contactData)
}

// Send out the intent to start the device's contacts app in its add contact activity.
startActivity(insertIntent)

Java

// Gets values from the UI
String name = contactNameEditText.getText().toString();
String phone = contactPhoneEditText.getText().toString();
String email = contactEmailEditText.getText().toString();

String company = companyName.getText().toString();
String jobtitle = jobTitle.getText().toString();

// Creates a new intent for sending to the device's contacts application
Intent insertIntent = new Intent(ContactsContract.Intents.Insert.ACTION);

// Sets the MIME type to the one expected by the insertion activity
insertIntent.setType(ContactsContract.RawContacts.CONTENT_TYPE);

// Sets the new contact name
insertIntent.putExtra(ContactsContract.Intents.Insert.NAME, name);

// Sets the new company and job title
insertIntent.putExtra(ContactsContract.Intents.Insert.COMPANY, company);
insertIntent.putExtra(ContactsContract.Intents.Insert.JOB_TITLE, jobtitle);

/*
 * Demonstrates adding data rows as an array list associated with the DATA key
 */

// Defines an array list to contain the ContentValues objects for each row
ArrayList<ContentValues> contactData = new ArrayList<ContentValues>();


/*
 * Defines the raw contact row
 */

// Sets up the row as a ContentValues object
ContentValues rawContactRow = new ContentValues();

// Adds the account type and name to the row
rawContactRow.put(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.getType());
rawContactRow.put(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.getName());

// Adds the row to the array
contactData.add(rawContactRow);

/*
 * Sets up the phone number data row
 */

// Sets up the row as a ContentValues object
ContentValues phoneRow = new ContentValues();

// Specifies the MIME type for this data row (all data rows must be marked by their type)
phoneRow.put(
        ContactsContract.Data.MIMETYPE,
        ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE
);

// Adds the phone number and its type to the row
phoneRow.put(ContactsContract.CommonDataKinds.Phone.NUMBER, phone);

// Adds the row to the array
contactData.add(phoneRow);

/*
 * Sets up the email data row
 */

// Sets up the row as a ContentValues object
ContentValues emailRow = new ContentValues();

// Specifies the MIME type for this data row (all data rows must be marked by their type)
emailRow.put(
        ContactsContract.Data.MIMETYPE,
        ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE
);

// Adds the email address and its type to the row
emailRow.put(ContactsContract.CommonDataKinds.Email.ADDRESS, email);

// Adds the row to the array
contactData.add(emailRow);

/*
 * Adds the array to the intent's extras. It must be a parcelable object in order to
 * travel between processes. The device's contacts app expects its key to be
 * Intents.Insert.DATA
 */
insertIntent.putParcelableArrayListExtra(ContactsContract.Intents.Insert.DATA, contactData);

// Send out the intent to start the device's contacts app in its add contact activity.
startActivity(insertIntent);

由于联系人仓库包含用户期望正确且最新的重要敏感数据,因此联系人提供程序具有明确的数据完整性规则。当您修改联系人数据时,您有责任遵守这些规则。重要规则列在此处

对于您添加的每个 ContactsContract.RawContacts 行,始终添加一个 ContactsContract.CommonDataKinds.StructuredName 行。

添加新的 ContactsContract.RawContacts 行时,务必为其添加对应的 ContactsContract.CommonDataKinds.StructuredName 行。
没有在 ContactsContract.Data 表中包含 ContactsContract.CommonDataKinds.StructuredName 行的 ContactsContract.RawContacts 行可能会在聚合期间引发问题。
务必将新的 ContactsContract.Data 行与其父级 ContactsContract.RawContacts 行关联。
未与 ContactsContract.RawContacts 关联的 ContactsContract.Data 行将无法在设备联系人应用中显示,并可能导致同步适配器出现问题。
仅更改您拥有的原始联系人的数据。
请记住,联系人提供程序通常管理来自多个不同帐号类型/在线服务的数据。您需要确保您的应用仅修改或删除属于您的行的数据,并且仅使用您控制的帐号类型和名称插入数据。
对于授权、内容 URI、URI 路径、列名称、MIME 类型和 TYPE 值,请务必使用 ContactsContract 及其子类中定义的常量。
使用这些常量有助于您避免错误。如果任何常量已弃用,您还会收到编译器警告。

自定义数据行

通过创建和使用您自己的自定义 MIME 类型,您可以在 ContactsContract.Data 表中插入、编辑、删除和检索您自己的数据行。您的行仅限于使用 ContactsContract.DataColumns 中定义的列,不过您可以将您自己的类型特定列名称映射到默认列名称。在设备的联系人应用中,您的行数据会显示,但无法编辑或删除,并且用户无法添加更多数据。要允许用户修改您的自定义数据行,您必须在自己的应用中提供一个编辑器 Activity。

要显示您的自定义数据,请提供一个 contacts.xml 文件,其中包含一个 <ContactsAccountType> 元素及其一个或多个 <ContactsDataKind> 子元素。这在 <ContactsDataKind> element 部分中有更详细的介绍。

要详细了解自定义 MIME 类型,请阅读创建内容提供程序指南。

联系人提供程序同步适配器

联系人提供程序专门用于处理设备与在线服务之间联系人数据的同步。这允许用户将现有数据下载到新设备,并将现有数据上传到新帐号。同步还能确保用户随时掌握最新数据,无论数据添加和更改的来源如何。同步的另一个优点是,即使设备未连接到网络,也能使联系人数据可用。

尽管您可以通过各种方式实现同步,但 Android 系统提供了一个即插即用同步框架,该框架可自动执行以下任务:

  • 检查网络可用性。
  • 根据用户偏好调度和执行同步。
  • 重启已停止的同步。

要使用此框架,您需要提供一个同步适配器插件。每个同步适配器对于服务和内容提供程序而言都是唯一的,但可以处理同一服务的多个帐号名称。该框架还允许为同一服务和提供程序设置多个同步适配器。

同步适配器类和文件

您可以将同步适配器实现为 AbstractThreadedSyncAdapter 的子类,并将其作为 Android 应用的一部分进行安装。系统会从您的应用清单中的元素以及清单指向的特殊 XML 文件中了解同步适配器。XML 文件定义了在线服务的帐号类型和内容提供程序的权限,这两者一起唯一标识适配器。同步适配器只有在用户添加该同步适配器帐号类型的帐号并为同步适配器同步的内容提供程序启用同步后才会激活。此时,系统开始管理该适配器,并在必要时调用它来同步内容提供程序与服务器之间的数据。

注意:使用帐号类型作为同步适配器标识的一部分,可让系统检测并分组来自同一组织访问不同服务的同步适配器。例如,Google 在线服务的同步适配器都具有相同的帐号类型 com.google。当用户在其设备中添加 Google 帐号时,所有已安装的 Google 服务同步适配器都会一起列出;列出的每个同步适配器都与设备上的不同内容提供程序同步。

由于大多数服务要求用户在访问数据之前验证身份,Android 系统提供了一个身份验证框架,该框架与同步适配器框架类似,并且经常结合使用。身份验证框架使用即插即用身份验证器,这些身份验证器是 AbstractAccountAuthenticator 的子类。身份验证器通过以下步骤验证用户身份:

  1. 收集用户的姓名、密码或类似信息(用户的凭据)。
  2. 将凭据发送到服务。
  3. 检查服务的回复。

如果服务接受凭据,身份验证器可以存储凭据供以后使用。由于采用即插即用身份验证器框架,AccountManager 可以提供对身份验证器支持并选择公开的任何身份验证令牌的访问,例如 OAuth2 身份验证令牌。

虽然身份验证并非强制要求,但大多数联系人服务都使用它。但是,您无需使用 Android 身份验证框架进行身份验证。

同步适配器实现

要实现联系人提供程序的同步适配器,首先需要创建一个包含以下内容的 Android 应用:

一个 Service 组件,用于响应系统绑定到同步适配器的请求。
当系统要运行同步时,会调用服务的 onBind() 方法以获取同步适配器的 IBinder。这使得系统能够跨进程调用适配器的方法。
实际的同步适配器,实现为 AbstractThreadedSyncAdapter 的具体子类。
此类负责从服务器下载数据、从设备上传数据以及解决冲突。适配器的主要工作在 onPerformSync() 方法中完成。此类必须实例化为单例模式。
Application 的子类。
此类用作同步适配器单例的工厂。使用 onCreate() 方法实例化同步适配器,并提供一个静态“getter”方法将单例返回给同步适配器服务的 onBind() 方法。
可选: 一个 Service 组件,用于响应系统对用户身份验证的请求。
AccountManager 启动此服务以开始身份验证过程。服务的 onCreate() 方法实例化一个身份验证器对象。当系统要对应用同步适配器的用户帐号进行身份验证时,会调用服务的 onBind() 方法以获取身份验证器的 IBinder。这使得系统能够跨进程调用身份验证器的方法。
可选: AbstractAccountAuthenticator 的具体子类,用于处理身份验证请求。
此类提供了由 AccountManager 调用的方法,用于验证用户与服务器之间的凭据。身份验证过程的详细信息因所使用的服务器技术而异。您应查阅服务器软件的文档以详细了解身份验证。
向系统定义同步适配器和身份验证器的 XML 文件。
前面描述的同步适配器和身份验证器服务组件在应用清单的 <service> 元素中定义。这些元素包含 <meta-data> 子元素,这些子元素向系统提供特定数据:
  • 同步适配器服务的 <meta-data> 元素指向 XML 文件 res/xml/syncadapter.xml。反过来,此文件指定将与联系人提供程序同步的 Web 服务的 URI 以及 Web 服务的帐号类型。
  • 可选: 身份验证器的 <meta-data> 元素指向 XML 文件 res/xml/authenticator.xml。反过来,此文件指定此身份验证器支持的帐号类型,以及在身份验证过程中出现的 UI 资源。此元素中指定的帐号类型必须与为同步适配器指定的帐号类型相同。

社交动态数据

android.provider.ContactsContract.StreamItems 和 android.provider.ContactsContract.StreamItemPhotos 表管理来自社交网络的传入数据。您可以编写一个同步适配器,将您自己网络中的动态数据添加到这些表中,或者您可以从这些表中读取动态数据并在您自己的应用中显示,或者两者兼而有之。通过这些功能,您的社交网络服务和应用可以集成到 Android 的社交网络体验中。

社交动态文本

动态项始终与原始联系人关联。android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID 链接到原始联系人的 _ID 值。原始联系人的帐号类型和帐号名称也存储在动态项行中。

将您的动态数据存储在以下列中:

android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_TYPE
必填。与此动态项关联的原始联系人的用户帐号类型。插入动态项时请务必设置此值。
android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_NAME
必填。与此动态项关联的原始联系人的用户帐号名称。插入动态项时请务必设置此值。
标识符列
必填。插入动态项时,您必须插入以下标识符列:
  • android.provider.ContactsContract.StreamItemsColumns#CONTACT_ID:与此动态项关联的联系人的 android.provider.BaseColumns#_ID 值。
  • android.provider.ContactsContract.StreamItemsColumns#CONTACT_LOOKUP_KEY:与此动态项关联的联系人的 android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY 值。
  • android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID:与此动态项关联的原始联系人的 android.provider.BaseColumns#_ID 值。
android.provider.ContactsContract.StreamItemsColumns#COMMENTS
可选。存储摘要信息,您可以在动态项开头显示。
android.provider.ContactsContract.StreamItemsColumns#TEXT
动态项的文本,可以是动态项来源发布的内容,也可以是生成动态项的某个操作的描述。此列可以包含 fromHtml() 可呈现的任何格式和嵌入的资源图片。提供程序可能会截断或省略过长的内容,但会尽量避免破坏标签。
android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP
一个文本字符串,包含动态项插入或更新的时间,格式为自纪元以来的毫秒数。插入或更新动态项的应用负责维护此列;联系人提供程序不会自动维护此列。

要显示您的动态项的标识信息,请使用 android.provider.ContactsContract.StreamItemsColumns#RES_ICON、android.provider.ContactsContract.StreamItemsColumns#RES_LABEL 和 android.provider.ContactsContract.StreamItemsColumns#RES_PACKAGE 链接到您应用中的资源。

android.provider.ContactsContract.StreamItems 表还包含 android.provider.ContactsContract.StreamItemsColumns#SYNC1 到 android.provider.ContactsContract.StreamItemsColumns#SYNC4 列,供同步适配器专享使用。

社交动态照片

android.provider.ContactsContract.StreamItemPhotos 表存储与动态项关联的照片。该表的 android.provider.ContactsContract.StreamItemPhotosColumns#STREAM_ITEM_ID 列链接到 android.provider.ContactsContract.StreamItems 表的 _ID 列中的值。照片引用存储在该表的以下列中:

android.provider.ContactsContract.StreamItemPhotos#PHOTO 列(一个 BLOB)。
照片的二进制表示,由提供程序调整大小以用于存储和显示。此列可用于与之前版本联系人提供程序的向后兼容性,之前的版本曾使用此列存储照片。但是,在当前版本中,您不应使用此列存储照片。而是应使用 android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID 或 android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI(这两者都将在以下几点中描述)将照片存储到文件中。此列现在包含照片的缩略图,可供读取。
android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID
原始联系人照片的数字标识符。将此值附加到常量 DisplayPhoto.CONTENT_URI 以获取指向单个照片文件的内容 URI,然后调用 openAssetFileDescriptor() 以获取照片文件的句柄。
android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI
直接指向此行表示的照片的照片文件的内容 URI。使用此 URI 调用 openAssetFileDescriptor() 以获取照片文件的句柄。

使用社交动态表

这些表与联系人提供程序中的其他主表工作方式相同,但以下情况除外:

  • 这些表需要额外的访问权限。要读取它们,您的应用必须具有权限 android.Manifest.permission#READ_SOCIAL_STREAM。要修改它们,您的应用必须具有权限 android.Manifest.permission#WRITE_SOCIAL_STREAM。
  • 对于 android.provider.ContactsContract.StreamItems 表,为每个原始联系人存储的行数是有限的。一旦达到此限制,联系人提供程序将通过自动删除具有最旧 android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP 的行来为新的动态项行腾出空间。要获取限制,请向内容 URI android.provider.ContactsContract.StreamItems#CONTENT_LIMIT_URI 发出查询。您可以将内容 URI 以外的所有参数设置为 null。查询会返回一个 Cursor,其中包含单行和单列 android.provider.ContactsContract.StreamItems#MAX_ITEMS。

类 android.provider.ContactsContract.StreamItems.StreamItemPhotos 定义了 android.provider.ContactsContract.StreamItemPhotos 的子表,其中包含单个动态项的照片行。

社交动态互动

联系人提供程序管理的社交动态数据与设备的联系人应用结合使用,提供了一种强大的方式将您的社交网络系统与现有联系人连接起来。以下功能可用:

  • 通过使用同步适配器将您的社交网络服务同步到联系人提供程序,您可以检索用户联系人的近期活动并将其存储在 android.provider.ContactsContract.StreamItems 和 android.provider.ContactsContract.StreamItemPhotos 表中,以便后续使用。
  • 除了常规同步外,当用户选择联系人进行查看时,您可以触发同步适配器检索更多数据。这允许您的同步适配器检索联系人的高分辨率照片和最新动态项。
  • 通过在设备的联系人应用和联系人提供程序注册通知,您可以在查看联系人时收到一个 Intent,并在此时从您的服务更新联系人的状态。这种方法可能比使用同步适配器进行完全同步更快,并且使用更少的带宽。
  • 用户可以在设备的联系人应用中查看联系人时,将该联系人添加到您的社交网络服务中。您可以通过“邀请联系人”功能启用此功能,此功能需要结合一个用于将现有联系人添加到您网络的 Activity,以及一个向设备联系人应用和联系人提供程序提供您的应用详细信息的 XML 文件。

动态项与联系人提供程序的常规同步与其他同步相同。要详细了解同步,请参阅联系人提供程序同步适配器部分。注册通知和邀请联系人将在接下来的两个部分介绍。

注册处理社交网络视图

要注册您的同步适配器以便在用户查看由您的同步适配器管理的联系人时接收通知,请执行以下操作:

  1. 在您项目的 res/xml/ 目录中创建一个名为 contacts.xml 的文件。如果您已有此文件,则可以跳过此步骤。
  2. 在此文件中,添加元素 <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">。如果此元素已存在,则可以跳过此步骤。
  3. 要注册一个服务,以便在用户在设备联系人应用中打开联系人详情页面时收到通知,请将属性 viewContactNotifyService="serviceclass" 添加到元素中,其中 serviceclass 是应接收设备联系人应用 Intent 的服务的完全限定类名。对于通知服务,请使用扩展 IntentService 的类,以允许服务接收 Intent。传入 Intent 中的数据包含用户点击的原始联系人的内容 URI。从通知服务中,您可以绑定到同步适配器,然后调用它来更新原始联系人的数据。

要注册一个 Activity,以便在用户点击动态项或照片或两者时被调用,请执行以下操作:

  1. 在您项目的 res/xml/ 目录中创建一个名为 contacts.xml 的文件。如果您已有此文件,则可以跳过此步骤。
  2. 在此文件中,添加元素 <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">。如果此元素已存在,则可以跳过此步骤。
  3. 要注册您的一个 Activity 以处理用户在设备联系人应用中点击动态项,请将属性 viewStreamItemActivity="activityclass" 添加到元素中,其中 activityclass 是应接收设备联系人应用 Intent 的 Activity 的完全限定类名。
  4. 要注册您的一个 Activity 以处理用户在设备联系人应用中点击动态照片,请将属性 viewStreamItemPhotoActivity="activityclass" 添加到元素中,其中 activityclass 是应接收设备联系人应用 Intent 的 Activity 的完全限定类名。

<ContactsAccountType> 元素在<ContactsAccountType> element 部分中有更详细的介绍。

传入的 Intent 包含用户点击的项或照片的内容 URI。要为文本项和照片设置单独的 Activity,请在同一文件中使用这两个属性。

与您的社交网络服务互动

用户无需离开设备的联系人应用即可邀请联系人加入您的社交网站。相反,您可以让设备的联系人应用发送一个 Intent,邀请联系人加入您的某个 Activity。要进行设置:

  1. 在您项目的 res/xml/ 目录中创建一个名为 contacts.xml 的文件。如果您已有此文件,则可以跳过此步骤。
  2. 在此文件中,添加元素 <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">。如果此元素已存在,则可以跳过此步骤。
  3. 添加以下属性:
    • inviteContactActivity="activityclass"
    • inviteContactActionLabel="@string/invite_action_label"
    activityclass 值是应接收 Intent 的 Activity 的完全限定类名。invite_action_label 值是显示在设备联系人应用的添加连接菜单中的文本字符串。例如,您可以使用字符串“在我的网络中关注”。您可以为此标签使用字符串资源标识符。

注意: ContactsSourceContactsAccountType 已弃用的标记名称。

contacts.xml 参考

文件 contacts.xml 包含控制您的同步适配器和应用与联系人应用及联系人提供程序交互的 XML 元素。以下部分描述了这些元素。

<ContactsAccountType> 元素

<ContactsAccountType> 元素控制您的应用与联系人应用的交互。它具有以下语法:

<ContactsAccountType
        xmlns:android="http://schemas.android.com/apk/res/android"
        inviteContactActivity="activity_name"
        inviteContactActionLabel="invite_command_text"
        viewContactNotifyService="view_notify_service"
        viewGroupActivity="group_view_activity"
        viewGroupActionLabel="group_action_text"
        viewStreamItemActivity="viewstream_activity_name"
        viewStreamItemPhotoActivity="viewphotostream_activity_name">

包含在

res/xml/contacts.xml

可包含

<ContactsDataKind>

说明

声明 Android 组件和 UI 标签,允许用户邀请其联系人之一加入社交网络,在用户社交网络动态更新时通知用户等。

请注意,<ContactsAccountType> 的属性不需要属性前缀 android:

属性

inviteContactActivity
当用户从设备联系人应用中选择添加连接时,您希望激活的应用中 Activity 的完全限定类名。
inviteContactActionLabel
添加连接菜单中,为 inviteContactActivity 中指定的 Activity 显示的文本字符串。例如,您可以使用字符串“在我的网络中关注”。您可以为此标签使用字符串资源标识符。
viewContactNotifyService
当用户查看联系人时应接收通知的应用中服务的完全限定类名。此通知由设备的联系人应用发送;它允许您的应用推迟数据密集型操作,直到需要时再执行。例如,您的应用可以通过读取并显示联系人的高分辨率照片和最新的社交动态项来响应此通知。此功能在社交动态互动部分中有更详细的介绍。
viewGroupActivity
您应用中可以显示群组信息的 Activity 的完全限定类名。当用户在设备联系人应用中点击群组标签时,将显示此 Activity 的 UI。
viewGroupActionLabel
联系人应用为允许用户查看您应用中群组的 UI 控件显示的标签。

此属性允许使用字符串资源标识符。

viewStreamItemActivity
设备联系人应用在用户点击原始联系人的动态项时启动的您应用中 Activity 的完全限定类名。
viewStreamItemPhotoActivity
设备联系人应用在用户点击原始联系人动态项中的照片时启动的您应用中 Activity 的完全限定类名。

<ContactsDataKind> 元素

<ContactsDataKind> 元素控制您的应用的自定义数据行在联系人应用的 UI 中的显示。它具有以下语法:

<ContactsDataKind
        android:mimeType="MIMEtype"
        android:icon="icon_resources"
        android:summaryColumn="column_name"
        android:detailColumn="column_name">

包含在

<ContactsAccountType>

说明

使用此元素让联系人应用将自定义数据行的内容显示为原始联系人详情的一部分。<ContactsAccountType> 的每个 <ContactsDataKind> 子元素表示您的同步适配器添加到 ContactsContract.Data 表中的一种自定义数据行类型。为您使用的每种自定义 MIME 类型添加一个 <ContactsDataKind> 元素。如果您有不想显示数据的自定义数据行,则无需添加此元素。

属性

android:mimeType
您在 ContactsContract.Data 表中为您的某个自定义数据行类型定义的自定义 MIME 类型。例如,值 vnd.android.cursor.item/vnd.example.locationstatus 可以是用于记录联系人最后已知位置的数据行的自定义 MIME 类型。
android:icon
Android drawable 资源,联系人应用会将其显示在您的数据旁边。使用此资源向用户指示数据来自您的服务。
android:summaryColumn
从数据行检索的两个值中的第一个的列名称。此值显示为此数据行条目的第一行。第一行旨在用作数据的摘要,但这并非强制要求。另请参阅 android:detailColumn
android:detailColumn
从数据行检索的两个值中的第二个的列名称。此值显示为此数据行条目的第二行。另请参阅 android:summaryColumn

其他联系人提供程序功能

除了前面部分描述的主要功能外,联系人提供程序还提供以下用于处理联系人数据的有用功能:

  • 联系人群组
  • 照片功能

联系人群组

联系人提供程序可以选择使用群组数据标记相关联系人的集合。如果与用户帐号关联的服务器希望维护群组,则该帐号类型的同步适配器应在联系人提供程序和服务器之间传输群组数据。当用户向服务器添加新联系人并将其置于新群组中时,同步适配器必须将新群组添加到 ContactsContract.Groups 表。原始联系人所属的群组存储在 ContactsContract.Data 表中,使用 ContactsContract.CommonDataKinds.GroupMembership MIME 类型。

如果您正在设计一个将服务器原始联系人数据添加到联系人提供程序的同步适配器,并且您不使用群组,则需要告知提供程序使您的数据可见。在用户向设备添加帐号时执行的代码中,更新联系人提供程序为该帐号添加的 ContactsContract.Settings 行。在此行中,将 Settings.UNGROUPED_VISIBLE 列的值设置为 1。执行此操作后,即使您不使用群组,联系人提供程序也将始终使您的联系人数据可见。

联系人照片

ContactsContract.Data 表以 MIME 类型为 Photo.CONTENT_ITEM_TYPE 的行存储照片。行的 CONTACT_ID 列链接到其所属原始联系人的 _ID 列。类 ContactsContract.Contacts.Photo 定义了 ContactsContract.Contacts 的子表,其中包含联系人主要照片的信息,即联系人主要原始联系人的主要照片。类似地,类 ContactsContract.RawContacts.DisplayPhoto 定义了 ContactsContract.RawContacts 的子表,其中包含原始联系人主要照片的信息。

ContactsContract.Contacts.PhotoContactsContract.RawContacts.DisplayPhoto 的参考文档包含检索照片信息的示例。没有方便的类来检索原始联系人的主要缩略图,但您可以向 ContactsContract.Data 表发送查询,按原始联系人的 _IDPhoto.CONTENT_ITEM_TYPEIS_PRIMARY 列进行选择,以查找原始联系人的主要照片行。

个人的社交动态数据也可能包含照片。这些照片存储在 android.provider.ContactsContract.StreamItemPhotos 表中,该表在社交动态照片部分中有更详细的介绍。