联系人提供程序

联系人提供程序是一个强大而又灵活的 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 值。

重要的原始联系人列

表 1 列出了 ContactsContract.RawContacts 表中的重要列。请阅读表后的说明：

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

备注

以下是关于 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. 第一个原始联系人对应“Thomas Higginson”，关联账号 emily.dickinson@gmail.com。 用户账号类型为 Google。
2. 第二个原始联系人对应“Thomas Higginson”，关联账号 emilyd@gmail.com。 用户账号类型也是 Google。由于添加的联系人对应的用户账号不同，因此尽管名称与前一名称完全相同，该联系人也只能作为第二个原始联系人。
3. 第三个原始联系人对应“Thomas Higginson”，关联账号“belle_of_amherst”。用户账号类型为 Twitter。

数据

如前所述，原始联系人的数据存储在一个 ContactsContract.Data 行中，该行链接到原始联系人的 _ID 值。基于此，一位原始联系人便可拥有多个数据类型相同的实例，如电子邮件地址或电话号码。例如，如果对应 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 个通用列命名为 DATA1 至 DATA15，可普遍适用；还有四个通用列命名为 SYNC1 至 SYNC4，只应由同步适配器使用。无论行包含何种类型的数据，通用列名称常量始终有效。

DATA1 列已编入索引。联系人提供程序会预测查询次数最多的目标数据，并且总是会用此列存储该数据。例如，在电子邮件行中，此列包含实际的电子邮件地址。

按照惯例，DATA15 列为预留列，用于存储照片缩略图等二进制大型对象 (BLOB) 数据。

类型专用列名称

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

例如，ContactsContract.CommonDataKinds.Email 类为 ContactsContract.Data 行定义类型专用列名称常量，该行的 MIME 类型为 Email.CONTENT_ITEM_TYPE。该类包含电子邮件地址列的常量 ADDRESS。ADDRESS 的实际值为“data1”，与列的通用名称相同。

注意：请勿使用具有提供程序某个预定义 MIME 类型的行向 ContactsContract.Data 表中添加您自己的自定义数据。否则您可能会丢失数据，或导致提供程序发生故障。例如，如果某行具有 MIME 类型 Email.CONTENT_ITEM_TYPE，并且其在 DATA1 列包含用户名而非电子邮件地址，则不应添加该行。如果您为该行使用自定义的 MIME 类型，则可自由定义您自己的类型专用列名称，并按意愿使用这些列。

图 2 显示的是描述性列和数据列在 ContactsContract.Data 行中的显示情况，以及类型专用列名称“覆盖”通用列名称的情况

图 2. 类型专用列名称和通用列名称。

类型专用列名称类

表 2 列出了最常用的类型专用列名称类：

表 2. 类型专用列名称类

通讯录

联系人提供程序会将所有账号类型和账号名称的原始联系人行进行合并，从而形成联系人。这有助于显示和修改用户针对某一联系人收集的所有数据。联系人提供程序可管理新联系人行的创建，以及原始联系人与现有联系人行的合并。系统不允许应用或同步适配器添加联系人，并且联系人行中的某些列为只读列。

注意：如果您尝试通过 insert() 向联系人提供程序添加联系人，则会获得一个 UnsupportedOperationException 异常。如果您尝试更新列表中列为“只读”的列，则更新会被忽略。

如果新增的原始联系人与现有联系人均不匹配，则联系人提供程序会相应地创建新联系人。如果某个现有原始联系人的数据发生变化，不再匹配其之前关联的联系人，则提供程序也会执行此操作。如果应用或同步适配器创建的新原始联系人确实与某位现有联系人匹配，则系统会将二者合并。

联系人提供程序会利用 Contacts 表内联系人行的 _ID 列，将联系人行链接至其原始联系人行。原始联系人表 ContactsContract.RawContacts 的 CONTACT_ID 列包含与每个原始联系人行相关联的联系人行的 _ID 值。

ContactsContract.Contacts 表还有一个 LOOKUP_KEY 列，它也是指向联系人行的“永久”链接。由于联系人提供程序会自动维护联系人，因此可能会在合并或同步时相应地更改联系人行的 _ID 值。即使出现这种情况，合并了联系人 LOOKUP_KEY 的内容 URI CONTENT_LOOKUP_URI 仍将指向联系人行，这样，您就能使用 LOOKUP_KEY 保持指向“收藏”联系人的链接，以及执行其他操作。该列具有其自己的格式，与 _ID 列的格式无关。

图 3 展示三个主表的相互关系。

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

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

来自同步适配器的数据

虽然用户会直接将联系人数据输入至设备，但这些数据也会通过同步适配器从网络服务流入联系人提供程序，而该同步适配器会自动在设备与服务之间传送数据。同步适配器在系统控制下在后台运行，它们会调用 ContentResolver 方法来管理数据。

在 Android 中，与同步适配器协作的网络服务由账号类型进行标识。 每个同步适配器都与一个账号类型协作，但它可以支持该类型的多个账号名称。原始联系人数据来源部分对账号类型和账号名称做了简要描述。以下定义提供了更多详细信息，并描述了账号类型及账号名称与同步适配器及服务之间的关系。

账号类型

表示用户在其中存储数据的服务。在大多数情况下，用户需使用服务进行身份验证。例如，Google 通讯录是一个以代码 google.com 标识的账号类型。此值对应于 AccountManager 使用的账号类型。

账号名称

表示某个账号类型的特定账号或登录名。Google 通讯录账号与 Google 账号相同，均以电子邮件地址作为账号名称。 其他服务可能使用一个单词的用户名或数字 ID。

账号类型不必具有唯一性。用户可以配置多个 Google 通讯录账号，并将其数据下载到联系人提供程序；如果用户为个人账号名称和工作账号名称分别设置了一组联系人，则可能会发生此情况。账号名称通常具有唯一性。它们共同标识联系人提供程序与外部服务之间的具体数据流。

如果您想将服务的数据传送至联系人提供程序，则需编写您自己的同步适配器。联系人提供程序同步适配器部分对此做了更详尽的描述。

图 4 展示联系人提供程序如何适应联系人数据流。在标记为“sync adapters”（同步适配器）的方框中，每个适配器都以其账号类型命名。

图 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_CONTACTS 和 WRITE_CONTACTS 权限外，如果想访问用户个人资料，还分别需要 android.Manifest.permission#READ_PROFILE 和 android.Manifest.permission#WRITE_PROFILE 权限进行读取和写入访问。

请记住，您应将用户的个人资料视为敏感数据。借助 android.Manifest.permission#READ_PROFILE 权限，您可以访问设备用户的个人可识别数据。请务必在您的应用的说明中告知用户您需要用户个人资料访问权限的原因。

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

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

// 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”。

联系人提供程序元数据

联系人提供程序会对追踪存储区内联系人数据状态的数据进行管理。这类元数据与存储区有关且存储在各处，其中包括原始联系人表行、数据表行和联系人表行、ContactsContract.Settings 表以及 ContactsContract.SyncState 表。下表展示各个元数据部分的作用：

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

联系人提供程序访问

本部分介绍了访问联系人提供程序中数据的准则，重点介绍以下内容：

• 实体查询。
• 批量修改。
• 通过 intent 执行检索和修改。
• 数据完整性。

联系人提供程序同步适配器部分也详细阐述了如何通过同步适配器修改数据。

查询实体

联系人提供程序采用层次结构，有助于检索某一行以及与该行链接的所有“子”行。例如，如要显示某位联系人的所有信息，您可能需要检索某个 ContactsContract.Contacts 行的所有 ContactsContract.RawContacts 行，或者检索某个 ContactsContract.RawContacts 行的所有 ContactsContract.CommonDataKinds.Email 行。为便于执行此操作，联系人提供程序提供了实体构造，其作用类似于表间的数据库连接。

实体类似于一个表，该表由父表及其子表中的选定列组成。 查询实体时，您需根据实体中的可用列提供投影和搜索条件。结果会得到一个 Cursor，检索的每个子表行在其中都有一行与之对应。例如，如果您在 ContactsContract.Contacts.Entity 中查询某个联系人姓名，以及使用该姓名的所有原始联系人的所有 ContactsContract.CommonDataKinds.Email 行，则会获得一个 Cursor，每个 ContactsContract.CommonDataKinds.Email 行在其中都有一行与之对应。

实体可简化查询。使用实体时，您可以一次性检索联系人或原始联系人的所有联系人数据，而不必先通过查询父表获得 ID，然后通过该 ID 查询子表。此外，联系人提供程序可通过单一事务处理实体查询，从而确保所检索数据的内部一致性。

注意：实体通常不包含父表和子表的所有列。如果您试图使用的列名称并未出现在实体的列名称常量列表中，则会引发一个 Exception。

以下代码段展示了如何检索某位联系人的所有原始联系人行。该代码段取自某个大型应用，该应用包含两种 activity：“main”activity 和“detail”activity。主 activity 显示联系人行列表；当用户选择某一行时，该 activity 会将该行 ID 发送至详情 activity。详情 activity 使用 ContactsContract.Contacts.Entity 显示与所选联系人关联的所有原始联系人中的所有数据行。

以下代码段摘自“详情”activity：

...
    /*
     * 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.
    )
}

...
    /*
     * 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 获取数据，以进行显示或做进一步处理。

批量修改

您应尽可能通过创建 ContentProviderOperation 对象的 ArrayList 并调用 applyBatch()，以“批处理模式”在联系人提供程序中插入、更新和删除数据。由于联系人提供程序是在 applyBatch() 中通过单一事务执行所有操作，因此您的修改绝不会使联系人存储区出现不一致问题。此外，批量修改还有助于同时插入原始联系人及其详细数据。

注意：如要修改单个原始联系人，可以考虑向设备的联系人应用发送一个 intent，而不是在您的应用中处理修改。通过 intent 执行检索和修改部分对此操作做了更详尽的描述。

挂起点

如果某次批量修改需执行大量操作，则可能会阻塞其他进程，导致整体用户体验不佳。为将所有您想执行的修改操作尽量分散到各个集合中，并同时防止其阻塞系统，您需要为一项或多项操作设置屈服点。 挂起点是一个 ContentProviderOperation 对象，其 isYieldAllowed() 值设置为 true。当联系人提供程序遇到挂起点时，它会暂停其工作，让其他进程运行，并关闭当前事务。当提供程序再次启动时，它会继续执行 ArrayList 中的下一项操作，并启动新事务。

屈服点会导致每次调用 applyBatch() 时产生多个事务。因此，您应为一组相关行的最后一项操作设置挂起点。 例如，您应该为一组操作中添加原始联系人行及其关联数据行的最后一项操作设置挂起点，或者针对一组与某位联系人相关的行的最后一项操作设置屈服点。

挂起点也是一个原子操作单元。无论访问成功还是失败，两个挂起点之间的所有访问均以一个单元的形式呈现。如果您不设置任何挂起点，则最小的原子操作即为整个批量操作。如果您使用了屈服点，则可以防止操作降低系统性能，还可确保一部分操作是原子操作。

修改向后引用

在将新的原始联系人行及其关联的数据行作为一组 ContentProviderOperation 对象插入时，您需将原始联系人的 _ID 值作为 RAW_CONTACT_ID 值插入，从而将数据行链接到原始联系人行。不过，您在数据行创建 ContentProviderOperation 时仍无法使用该值，因为您尚未对原始联系人行应用 ContentProviderOperation。为解决此问题，ContentProviderOperation.Builder 类提供了 withValueBackReference() 方法。借助该方法，您可以插入或修改包含上一次操作结果的列。

withValueBackReference() 方法有两个参数：

key

键值对的键。此参数的值应为您要修改的表中某一列的名称。

previousResult

applyBatch() 中 ContentProviderResult 对象数组内某一值以 0 开始的索引。在应用批处理操作时，每个操作的结果均存储在结果的中间数组内。previousResult 值是其中某个结果的索引，并且需通过 key 值对其进行检索和存储。这样，您便可插入一条新的原始联系人记录，并取回其 _ID 值，然后在添加 ContactsContract.Data 行时“向后引用”该值。

系统会在您首次调用 applyBatch() 时创建整个结果数组，其大小与您提供的 ContentProviderOperation 对象的 ArrayList 大小相等。不过，结果数组中的所有元素均已设为 null。如果您试图向后引用某个尚未应用的操作的结果，则 withValueBackReference() 会抛出 Exception。

以下代码段展示了如何批量插入新原始联系人和数据。其中包括用于建立挂起点和使用向后引用的代码。

第一个代码段用于检索界面中的联系人数据。此时，用户已选择应添加新原始联系人的账号。

// 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]

// 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 表的操作：

    /*
     * 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())

    /*
     * 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());

接下来，代码会创建显示姓名行、电话行和电子邮件行的数据行。

每个操作的 Builder 对象均使用 withValueBackReference() 来获取 RAW_CONTACT_ID。引用指回第一次操作（添加原始联系人行并返回其新 _ID 值）的 ContentProviderResult 对象。结果是，每个数据行都通过其 RAW_CONTACT_ID 自动链接到其所属的新 ContactsContract.RawContacts 行。

添加电子邮件行的 ContentProviderOperation.Builder 对象带有 withYieldAllowed() 标记，用于设置挂起点：

    // 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())

    // 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() 调用，用于插入新原始联系人行和数据行。

    // 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")
    }
}

    // 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，请使用追加有原始联系人 _ID 的 RawContacts.CONTENT_URI。
3. 对于 ContentProviderOperation.Builder 对象，请调用 withValue()，将 VERSION 列与您刚检索的版本号进行比较。
4. 对于同一 ContentProviderOperation.Builder，请调用 withExpectedCount()，确保此断言只对一行进行测试。
5. 调用 build() 创建 ContentProviderOperation 对象，然后将此对象添加为要传递给 applyBatch() 的 ArrayList 中的第一个对象。
6. 应用批处理事务。

如果在读取原始联系人行和准备对其进行修改的这段时间内，如有另一项操作更新该行，则“断言”ContentProviderOperation 会失败，系统将终止整个批处理操作。此情况下，您可以选择重新执行批处理操作，或执行其他操作。

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

/*
 * 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
}

/*
 * 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 会启动设备的联系人应用界面，用户可以在该界面中执行与联系人相关的操作。通过这种访问方式，用户可以：

• 从列表中选取一位联系人并将其返回给您的应用以执行进一步操作。
• 修改现有联系人的数据。
• 为其任一账户插入新原始联系人。
• 删除联系人或联系人数据。

如果用户要插入或更新数据，您可以先收集数据，然后将其加入 intent 并发送。

在使用 intent 实现通过设备的联系人应用访问联系人提供程序时，您无需自行编写用于访问该提供程序的界面或代码。您也无需请求对提供程序的读取或写入权限。设备的通讯录应用可以将联系人读取权限授予给您，而且您是通过另一个应用对该提供程序进行修改，因此无需拥有写入权限。

如需详细了解通过发送 intent 来访问提供程序的常规步骤，请参阅 内容提供程序基础知识指南的“通过 intent 访问数据”部分。表 4 总结了可用任务中所用的操作、MIME 类型和数据值，而可用于 putExtra() 的 Extra 值则列在 ContactsContract.Intents.Insert 参考文档中：

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

设备的联系人应用不允许您使用 intent 删除原始联系人或其任何数据。因此，如要删除原始联系人，请使用 ContentResolver.delete() 或 ContentProviderOperation.newDelete()。

以下代码段展示了如何构建和发送插入新原始联系人和数据的 intent：

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

// 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.Data 表中的 ContactsContract.RawContacts 行没有 ContactsContract.CommonDataKinds.StructuredName 行，则可能会在汇总时遇到问题。

务必将新 ContactsContract.Data 行链接到其父级 ContactsContract.RawContacts 行。

如果 ContactsContract.Data 行未链接到 ContactsContract.RawContacts，则其在设备的通讯录应用中将处于不可见状态，而且这可能会导致同步适配器出现问题。

只更改您所拥有的原始联系人的数据。

请注意，联系人提供程序所管理的数据通常来自多个不同账号类型/在线服务。您需要确保您的应用仅修改或删除归您所有的行的数据，并且仅通过您控制的账号类型和账号名称插入数据。

务必使用在 ContactsContract 及其子类中为授权、内容 URI、URI 路径、列名称、MIME 类型以及 TYPE 值定义的常量。

使用这些常量有助于您避免错误。如有任何常量被弃用，您还会收到编译器警告。

自定义数据行

通过创建和使用自己的自定义 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。而该文件则指定将与联系人提供程序同步的网络服务的 URI，以及指定该 Web 服务的账号类型。
• 可选：身份验证器的 <meta-data> 元素指向 XML 文件 res/xml/authenticator.xml。而该文件则指定此身份验证器所支持的账号类型，以及身份验证过程中出现的界面资源。在此元素中指定的账号类型必须与为同步适配器指定的账号类型相同。

社交流数据

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 列（一个二进制大型对象）。

照片的二进制表示，由提供程序调整尺寸，以便存储和显示。 此列可用于向后兼容使用它来存储照片的旧版联系人提供程序。不过，在当前版本中，您不应使用此列来存储照片。而应使用 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 的子表，其中包含某个流项目的照片行。

社交流交互

通过将联系人提供程序管理的社交流数据与设备的联系人应用相结合，您可以在社交网络系统与现有联系人之间建立起有效的连接。可使用以下功能：

• 您可以通过同步适配器将您的社交网络服务与联系人提供程序进行同步，从而检索用户联系人的近期 activity，并将其存储在 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 是该 activity 的完全限定类名，并且应由该 activity 接收来自设备联系人应用的 intent。
4. 如要注册某个 activity，以处理用户在设备联系人应用中点击某个流照片的操作，请为该元素添加 viewStreamItemPhotoActivity="activityclass" 属性，其中 activityclass 是该 activity 的完全限定类名，并且应由该 activity 接收来自设备联系人应用的 intent。

<ContactsAccountType> 元素部分对 <ContactsAccountType> 元素做了更详尽的描述。

传入 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 值是一个文本字符串，将显示在设备联系人应用的添加关联菜单中。

注意：ContactsSource 是 ContactsAccountType 的一个已废弃的标记名称。

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 组件和界面标签，以便用户邀请他们的一位联系人加入社交网络、在其某个社交网络流更新时通知用户，以及执行其他操作。

请注意，对 <ContactsAccountType> 的属性而言，属性前缀 android: 并非必需的。

属性：

inviteContactActivity

您的应用中某个 activity 的完全限定类名，您想要在用户于设备的联系人应用中选择 Add connection 时激活该 activity。

inviteContactActionLabel

Add connection 菜单中为 inviteContactActivity 中指定的 activity 显示的文本字符串。 例如，您可以使用字符串“Follow in my network”。您可以为此标签使用字符串资源标识符。

viewContactNotifyService

您的应用中某项服务的完全限定类名，当用户查看联系人时，应由该服务接收通知。此通知由设备的联系人应用发送；您的应用可根据该通知将数据密集型操作推迟到必要时再执行。例如，您的应用可按如下方式响应该通知：读入并显示联系人的高分辨率照片和最近的社交流项目。社交流交互部分对此功能做了更详尽的描述。

viewGroupActivity

您的应用中某个可显示组信息的 activity 的完全限定类名。当用户点击设备联系人应用中的组标签时，系统会显示此 activity 的界面。

viewGroupActionLabel

联系人应用为某个界面控件显示的标签，用户可通过该控件查看您应用中的组。

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

viewStreamItemActivity

您的应用中某个 activity 的完全限定类名，当用户点击原始联系人的流项目时，设备的联系人应用会启动该 activity。

viewStreamItemPhotoActivity

您的应用中某个 activity 的完全限定类名，当用户点击原始联系人流项目中的照片时，设备的联系人应用会启动该 activity。

<ContactsDataKind> 元素

<ContactsDataKind> 元素控制着您应用的自定义数据行在通讯录应用界面中的显示。其语法如下：

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

包含在：

说明：

此元素用于让联系人应用将自定义数据行的内容显示为原始联系人详细信息的一部分。<ContactsAccountType> 的每个 <ContactsDataKind> 子元素都代表您的同步适配器向 ContactsContract.Data 表添加的某个自定义数据行类型。请为您使用的每个自定义 MIME 类型添加一个 <ContactsDataKind> 元素。如果您不想显示任何自定义数据行的数据，则无需添加该元素。

属性：

android:mimeType

您为 ContactsContract.Data 表中某个自定义数据行类型定义的自定义 MIME 类型。例如，可将值 vnd.android.cursor.item/vnd.example.locationstatus 作为记录联系人最后已知位置的数据行的自定义 MIME 类型。

android:icon

联系人应用在您的数据旁显示的 Android 可绘制对象资源。该属性用于向用户指明数据来自您的服务。

android:summaryColumn

从数据行检索的两个值中第一个值的列名。该值显示为该数据行的第一个输入行。第一行专用作数据摘要，但它是可选项。另请参阅 android:detailColumn。

android:detailColumn

从数据行检索的两个值中第二个值的列名。该值显示为该数据行的第二个输入行。另请参阅 android:summaryColumn。

其他联系人提供程序功能

除了上文描述的主要功能外，联系人提供程序还为处理联系人数据提供了下列实用功能：

• 联系人群组
• 照片功能

联系人群组

联系人提供程序可以选择性地为相关联系人集合添加组数据标签。如果与某个用户账号关联的服务器想要维护组，则与该账号的账号类型对应的同步适配器应在联系人提供程序与服务器之间传送组数据。当用户向服务器添加新联系人，然后将其放入新组时，同步适配器必须将该新组添加到 ContactsContract.Groups 表中。原始联系人所属的一个或多个组使用 ContactsContract.CommonDataKinds.GroupMembership MIME 类型存储在 ContactsContract.Data 表内。

如果您设计的同步适配器会将服务器中的原始联系人数据添加到联系人提供程序，并且您不使用组，则您需指示提供程序使您的数据可见。在用户向设备添加账号时执行的代码中，更新联系人提供程序为该账号添加的 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.Photo 和 ContactsContract.RawContacts.DisplayPhoto 参考文档包含检索照片信息的示例。没有可用来检索原始联系人主要缩略图的实用类，但您可以向 ContactsContract.Data 表发送查询，从而通过选定原始联系人的 _ID、Photo.CONTENT_ITEM_TYPE 和 IS_PRIMARY 列，找到原始联系人的主要照片行。

联系人的社交流数据也可能包含照片。这些照片存储在 android.provider.ContactsContract.StreamItemPhotos 表中，社交流照片部分对该表做了更详尽的描述。