Android NDK开发详解用户数据和身份之联系人提供程序
联系人提供程序是一个强大而又灵活的 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”
该用户已在 Accounts 设置中为这三个帐户启用了 Sync Contacts。
假定 Emily Dickinson 打开浏览器窗口，以 emily.dickinson@gmail.com 身份登录 Gmail，然后打开“联系人”，并添加“Thomas Higginson”。后来，她以 emilyd@gmail.com 身份登录 Gmail，并向“Thomas Higginson”发送一封电子邮件（此操作会自动将 Thomas Higginson 添加为联系人）。她还在 Twitter 上关注了“colonel_tom”（Thomas Higginson 的 Twitter ID）。
以上操作的结果是，联系人提供程序会创建以下三个原始联系人：
第一个原始联系人对应“Thomas Higginson”，关联帐户 emily.dickinson@gmail.com。用户帐户类型是 Google。
第二个原始联系人对应“Thomas Higginson”，关联帐户 emilyd@gmail.com。用户帐户类型也是 Google。由于添加的联系人对应不同的用户帐户，因此尽管名称与前一名称完全相同，该联系人也只能作为第二个原始联系人。
第三个原始联系人对应“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 列会标记包含该类型主要数据的数据行。例如，如果用户长按某个联系人的电话号码，并选择 Set default，则包含该号码的 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. 联系人表、原始联系人表与详细信息表之间的关系。
注意：如果您将应用发布到 Google Play 商店，或者如果应用所在设备运行 Android 10 (API 级别 29) 或更高版本，请记住，一组有限的联系人数据字段和方法已过时。
在上述条件下，系统会定期清除写入这些数据字段的任何值：
ContactsContract.ContactOptionsColumns.LAST_TIME_CONTACTED
ContactsContract.ContactOptionsColumns.TIMES_CONTACTED
ContactsContract.DataUsageStatColumns.LAST_TIME_USED
ContactsContract.DataUsageStatColumns.TIMES_USED
用于设置上述数据字段的 API 也已过时：
ContactsContract.Contacts.markAsContacted()
ContactsContract.DataUsageFeedback
此外，以下字段不再返回常用联系人。请注意，仅当联系人属于特定的数据类型时，其中一些字段才会影响联系人的排名。
ContactsContract.Contacts.CONTENT_FREQUENT_URI
ContactsContract.Contacts.CONTENT_STREQUENT_URI
ContactsContract.Contacts.CONTENT_STREQUENT_FILTER_URI
CONTENT_FILTER_URI（仅影响 Email、Phone、Callable 和 Contactables 数据类型）
ENTERPRISE_CONTENT_FILTER_URI（仅影响 Email、Phone 和 Callable 数据类型）
如果您的应用想访问或更新这些字段或 API，请使用其他方法。例如，您可以使用私有内容提供程序或存储在应用或后端系统中的其他数据来实现某些用例。
如要验证应用的功能不受此更改的影响，您可以手动清除这些数据字段。为此，请在运行 Android 4.1（API 级别 16）或更高版本的设备上运行以下 ADB 命令：
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 中使用 元素，以 的形式指定此权限。
对一个或多个表的写入权限
WRITE_CONTACTS，您需在 AndroidManifest.xml 中使用 元素，以 的形式指定此权限。
这些权限不适用于用户个人资料数据。如需了解用户个人资料及其所需权限的详细介绍，请参阅下面的用户个人资料部分。
请记住，用户的联系人数据属于个人敏感数据。用户关心个人隐私，因此不愿让应用收集自己或联系人的相关数据。如果应用无法提供明确的理由以使用权限访问用户联系人数据，则用户可能会对其做出差评或干脆拒绝安装。
用户个人资料
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。例如，以下代码段用于检索个人资料数据：
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”。
联系人提供程序元数据
联系人提供程序会对追踪存储区内联系人数据状态的数据进行管理。这类元数据与存储区有关且存储在各处，其中包括原始联系人表行、数据表行和联系人表行、ContactsContract.Settings 表以及 ContactsContract.SyncState 表。下表展示各个元数据部分的作用：
联系人提供程序访问
本部分描述如何访问联系人提供程序中的数据，重点介绍以下内容：
实体查询。
批量修改。
通过 Intent 执行检索和修改。
数据完整性。
此外，联系人提供程序同步适配器部分也详细阐述了如何通过同步适配器修改数据。
有关如何在搜索联系人时使用联系人提供程序的示例，请参阅基本 Contactables 示例。
查询实体
联系人提供程序采用层次结构，有助于检索某一行以及与该行链接的所有“子”行。例如，如要显示某位联系人的所有信息，您可能需要检索某个 ContactsContract.Contacts 行的所有 ContactsContract.RawContacts 行，或者检索某个 ContactsContract.RawContacts 行的所有 ContactsContract.CommonDataKinds.Email 行。为便于执行此操作，联系人提供程序提供实体构造，其作用类似于各个表之间的数据库连接。
实体类似于一个表，该表由父表及其子表中的选定列组成。查询实体时，您需根据实体中的可用列提供投影和搜索条件。结果会得到一个 Cursor，检索的每个子表行在其中都有一行与之对应。例如，如果您在 ContactsContract.Contacts.Entity 中查询某个联系人姓名，以及使用该姓名的所有原始联系人的所有 ContactsContract.CommonDataKinds.Email 行，则会获得一个 Cursor，每个 ContactsContract.CommonDataKinds.Email 行在其中都有一行与之对应。
实体可简化查询。使用实体时，您可以一次性检索联系人或原始联系人的所有联系人数据，而不必先通过查询父表获得 ID，继而通过该 ID 查询子表。此外，联系人提供程序可通过单一事务处理实体查询，从而确保所检索数据的内部一致性。
注意：实体通常不包含父表和子表的所有列。如果您试图使用的列名称并未出现在实体的列名称常量列表中，则程序会抛出 Exception。
以下代码段说明如何检索某位联系人的所有原始联系人行。该片段取自某个大型应用，该应用包含两种 Activity：“主”Activity和“详”Activity。主 Activity 显示联系人行列表；当用户选择某一行时，该 Activity 会将该行 ID 发送至详 Activity。详 Activity 使用 ContactsContract.Contacts.Entity 显示与所选联系人关联的所有原始联系人中的所有数据行。
以下代码段摘自“详”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 中获取数据，从而显示该数据或进一步对其进行处理。
批量修改
您应尽量通过创建 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() 的结果存储在索引值从 0 开始的 ContentProviderResult 对象数组中。在应用批处理操作时，每个操作的结果均存储在结果的中间数组内。previousResult 值是其中某个结果的索引，并且需通过 key 值对其进行检索和存储。这样，您便可插入一条新的原始联系人记录，并取回其 _ID 值，然后在添加 ContactsContract.Data 行时“向后引用”该值。
系统会在您首次调用 applyBatch() 时创建整个结果数组，其大小与您提供的 ContentProviderOperation 对象的 ArrayList 相等。不过，结果数组中的所有元素均已设为 null。如果您试图向后引用某个尚未应用的操作的结果，则 withValueBackReference() 会抛出 Exception。
以下代码段展示如何批量插入新原始联系人和数据。其中包括用于建立挂起点和使用向后引用的代码。
第一段代码用于检索界面中的联系人数据。此时，用户已选择应添加新原始联系人的帐户。
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());
接着，代码会创建显示姓名行、电话行和电子邮件行的数据行。
每个操作的 Builder 对象均使用 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 行时使用乐观并发控制，请按以下步骤操作：
检索原始联系人的 VERSION 列以及其他待检索数据。
创建适合使用 newAssertQuery(Uri) 方法强制执行约束的 ContentProviderOperation.Builder 对象。对于内容 URI，请使用追加有原始联系人 _ID 的 RawContacts.CONTENT_URI。
对于 ContentProviderOperation.Builder 对象，请调用 withValue()，将 VERSION 列与您刚检索的版本号进行比较。
对于同一 ContentProviderOperation.Builder，请调用 withExpectedCount()，确保此断言只对一行进行测试。
通过调用 build() 创建 ContentProviderOperation 对象，然后将此对象作为第一个对象添加到传递至 applyBatch() 的 ArrayList 中。
应用批处理事务。
在读取原始联系人行和准备对其进行修改的这段时间内，如有另一项操作更新该行，则“断言”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 会启动设备的联系人应用界面，用户可以在该界面中执行与联系人相关的操作。通过这种访问方式，用户可以：
从列表中选取一位联系人并将其返回给您的应用以执行进一步操作。
编辑现有联系人的数据。
为其任一帐户插入新原始联系人。
删除联系人或联系人数据。
如果用户要插入或更新数据，您可以先收集数据，然后将其加入 Intent 并发送。
在使用 Intent 实现通过设备的联系人应用访问联系人提供程序时，您无需自行编写用于访问该提供程序的界面或代码。您也无需请求对提供程序的读取或写入权限。设备的联系人应用可以为您授予联系人读取权限，并且您是通过另一个应用对该提供程序进行修改，因此无需拥有写入权限。
如需详细了解通过发送 Intent 来访问提供程序的常规步骤，请参阅内容提供程序基础知识指南的“通过 Intent 访问数据”部分。表 4 总结了可用任务中所用的操作、MIME 类型和数据值，而可用于 putExtra() 的 Extra 值则列在 ContactsContract.Intents.Insert 参考文档中：
表 4. 联系人提供程序 Intent。
调用 startActivityForResult() 方法，该方法返回所选行的内容 URI。该 URI 的形式为：追加有该行 LOOKUP_ID 的表的内容 URI。设备的联系人应用会在 Activity 的生命周期内为此内容 URI 授予读取和写入权限。如需了解更多详情，请参阅内容提供程序基础知识指南。
插入新原始联系人 Insert.ACTION 不适用 RawContacts.CONTENT_TYPE，用于一组原始联系人的 MIME 类型。 显示设备联系人应用的添加联系人屏幕。系统会显示您添加到 Intent 中的 Extra 值。如果使用 startActivityForResult() 发送新增原始联系人的内容 URI，则系统会将其回传给 Activity 的 onActivityResult() 回调方法，回传形式为该方法 Intent 参数的“data”字段。如要获取该值，请调用 getData()。
插入联系人 ACTION_EDIT 联系人的 CONTENT_LOOKUP_URI。用户可使用编辑 Activity 编辑任何与此联系人关联的数据。 Contacts.CONTENT_ITEM_TYPE，单个联系人。 显示联系人应用中的“编辑联系人”屏幕。系统会显示您添加到 Intent 中的 Extra 值。当用户点击 Done 保存编辑时，您的 Activity 会返回前台。
显示同样可添加数据的选择器。 ACTION_INSERT_OR_EDIT 不适用 CONTENT_ITEM_TYPE 此 Intent 始终显示联系人应用的选择器屏幕。用户可选取要编辑的联系人，或添加新联系人。系统会根据用户的选择显示编辑界面或添加界面，还会显示您使用 Intent 传递的 Extra 数据。如果您的应用显示电子邮件或电话号码等联系人数据，请使用此 Intent，以便用户向现有联系人添加数据。
注意：无需通过此 Intent 的 Extra 数据发送姓名值，因为用户总是会选取现有姓名或添加新姓名。此外，如果您发送姓名，并且用户选择执行编辑操作，则联系人应用将显示您发送的姓名，该姓名将覆盖先前的值。如果用户未注意此情况便保存了编辑，则旧值会丢失。
设备的联系人应用不允许您使用 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.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 文件，其中需包含 元素，及该元素的一个或多个 子元素。 element 部分详细介绍了此内容。
如需了解有关自定义 MIME 类型的更多信息，请阅读创建内容提供程序指南。
联系人提供程序同步适配器
联系人提供程序专用于处理设备与在线服务之间的联系人数据同步。借助同步功能，用户可以将现有数据下载到新设备，并将现有数据上传到新帐户。同步还能确保用户手握最新数据，无需考虑数据增加和更改的来源。同步的另一个优点是，即使设备未连接网络，它也能让用户使用联系人数据。
虽然您可以通过各种方式实现同步，不过 Android 系统提供了一个插件同步框架，可自动完成下列任务：
检查网络可用性。
根据用户偏好安排和执行同步。
重启已停止的同步。
如要使用此框架，您需提供同步适配器插件。每个同步适配器专供某个服务和内容提供程序使用，但可以处理同一服务的多个帐户名称。该框架还允许同一服务和提供程序拥有多个同步适配器。
同步适配器类和文件
您需要以 AbstractThreadedSyncAdapter 子类的形式实现同步适配器，并将其安装为 Android 应用的一部分。系统会通过应用清单文件中的元素以及清单文件指向的特殊 XML 文件，了解同步适配器的相关信息。该 XML 文件定义在线服务的帐户类型和内容提供程序的权限，二者共同对适配器进行唯一标识。只有当用户为同步适配器的帐户类型添加帐户，并为与同步适配器同步的内容提供程序启用同步后，同步适配器才会激活。激活后，系统将开始管理适配器，并在必要时调用该适配器，以在内容提供程序与服务器之间同步数据。
注意：通过将帐户类型用作同步适配器标识的部分内容，系统可检测出从同一帐户类型访问不同服务的同步适配器，并对其进行分类。例如，Google 在线服务的同步适配器都拥有相同的帐户类型 com.google。当用户向其设备添加 Google 帐户时，系统会一同列出所有已安装的 Google 服务同步适配器；列出的每个同步适配器都会与设备上的不同内容提供程序进行同步。
大多数服务都要求用户在验证身份后访问数据，为此，Android 系统提供身份验证框架，该框架与同步适配器框架类似，并且经常与其联用。该身份验证框架使用的插件身份验证器是 AbstractAccountAuthenticator 的子类。身份验证器通过下列步骤验证用户的身份：
收集用户名、用户密码或类似信息（用户的凭据）。
将凭据发送给服务。
检查服务的回复。
如果服务接受凭据，身份验证器便可存储凭据以供日后使用。由于插件身份验证器框架的存在，AccountManager 可以访问身份验证器支持并选择公开的任何身份验证令牌（例如 OAuth2 身份验证令牌）。
尽管身份验证并非必需，但大多数联系人服务都会使用它。不过，您不一定要使用 Android 身份验证框架进行身份验证。
同步适配器实现
如要为联系人提供程序实现同步适配器，您首先需创建包含以下内容的 Android 应用：
一个 Service 组件，用于响应系统发出的绑定到同步适配器的请求。
当系统想要运行同步时，它会调用服务的 onBind() 方法，为同步适配器获取一个 IBinder。这样，系统便可跨进程调用适配器的方法。
作为 AbstractThreadedSyncAdapter 具体子类实现的实际同步适配器。
此类的作用是从服务器下载数据、从设备上传数据以及解决冲突。系统会在 onPerformSync() 方法会完成适配器的主要工作。必须将此类实例化为单例。
Application 的子类。
此类充当同步适配器单例的工厂。使用 onCreate() 方法实例化同步适配器，并提供一个静态“getter”方法，使单例返回同步适配器服务的 onBind() 方法。
可选：一个 Service 组件，用于响应系统发出的用户身份验证请求。
AccountManager 会启动此服务以开始身份验证流程。该服务的 onCreate() 方法会实例化一个身份验证器对象。当系统想要对应用同步适配器的用户帐户进行身份验证时，它会调用该服务的 onBind() 方法，为该身份验证器获取一个 IBinder。这样，系统便可跨进程调用身份验证器的方法。
可选：用于处理身份验证请求的 AbstractAccountAuthenticator 的具体子类。
此类会为 AccountManager 提供调用的方法，以便其通过服务器验证用户的凭据。具体的身份验证过程会因服务器所采用的技术而有很大差异。如要了解身份验证的相关详情，请参阅服务器软件的文档。
用于定义系统同步适配器和身份验证器的 XML 文件。
应用清单文件的 元素内定义了先前描述的同步适配器和身份验证器服务组件。这些元素包含以下 子元素，可以为系统提供特定数据：
同步适配器服务的 <meta-data> 元素指向XML 文件 res/xml/syncadapter.xml。而该文件会指定与联系人提供程序同步的网络服务的 URI，以及该网络服务的帐户类型。
可选：身份验证器的 <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 文件结合使用来实现的，前者将现有联系人添加到您的社交网络，后者为设备的联系人应用和联系人提供程序提供您应用的相关详情。
流项目与联系人提供程序的定期同步与其他同步相同。如需了解有关同步的更多信息，请参阅联系人提供程序同步适配器部分。接下来的两部分介绍如何注册通知和邀请联系人。
通过注册处理社交网络查看
如要注册您的同步适配器，以便在用户查看由其管理的联系人时收到通知，请执行以下步骤：
在项目的 res/xml/ 目录中创建名为 contacts.xml 的文件。如果您已有该文件，可跳过此步骤。
在该文件中添加 <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"> 元素。如果该元素已存在，可跳过此步骤。
如要注册一项服务，以便在用户于设备的联系人应用中打开某位联系人的详情页面时通知该服务，请为该元素添加 viewContactNotifyService="serviceclass" 属性，其中 serviceclass 是该服务的完全限定类名，并且应由该服务接收来自设备联系人应用的 Intent。对于此通知程序服务，请使用扩展 IntentService 的类，以便该服务能够接收 Intent。传入 Intent 中的数据包含用户所点击的原始联系人的内容 URI。您可以使用通知程序服务绑定到您的同步适配器，然后调用该同步适配器更新原始联系人的数据。
如要注册用户点击流项目或照片（或同时点击二者）时所调用的 Activity，请执行以下步骤：
在项目的 res/xml/ 目录中创建名为 contacts.xml 的文件。如果您已有该文件，可跳过此步骤。
在该文件中添加 <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"> 元素。如果该元素已存在，可跳过此步骤。
如要注册某个 Activity，以处理用户在设备联系人应用中点击某个流项目的操作，请为该元素添加 viewStreamItemActivity="activityclass" 属性，其中 activityclass 是该 Activity 的完全限定类名，并且应由该 Activity 接收来自设备联系人应用的 Intent。
如要注册某个 Activity，以处理用户在设备联系人应用中点击某个流照片的操作，请为该元素添加 viewStreamItemPhotoActivity="activityclass" 属性，其中 activityclass 是该 Activity 的完全限定类名，并且应由该 Activity 接收来自设备联系人应用的 Intent。
元素部分对 元素做了更详尽的描述。
传入 Intent 包含用户所点击的项目或照片的内容 URI。要让文本项目和照片具有独立的 Activity，请在同一文件中使用这两个属性。
与您的社交网络服务进行交互
在邀请联系人访问您的社交网络网站时，用户无需离开设备的联系人应用。您可以让设备的联系人应用发送一个 Intent，将联系人邀请到您的其中一个 Activity。如要设置此功能，请执行以下步骤：
在项目的 res/xml/ 目录中创建名为 contacts.xml 的文件。如果您已有该文件，可跳过此步骤。
在该文件中添加 <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"> 元素。如果该元素已存在，可跳过此步骤。
添加以下属性：
inviteContactActivity="activityclass"
inviteContactActionLabel="@string/invite_action_label"
activityclass 值是应接收该 Intent 的 Activity 的完全限定类名。invite_action_label 值是一个文本字符串，其显示在设备联系人应用的 Add Connection 菜单中。
注意：ContactsSource 是 ContactsAccountType 的一个已弃用的标记名称。
contacts.xml 引用
contacts.xml 文件包含一些 XML 元素，其会控制同步适配器和应用与联系人应用及联系人提供程序的交互。下文将对这些元素进行描述。
元素
元素控制您的应用与联系人应用的交互。该元素采用以下语法：
<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
可包含：
说明：
声明 Android 组件和界面标签，以便用户邀请他们的一位联系人加入社交网络、在其某个社交网络流更新时通知用户，以及执行其他操作。
请注意，对 的属性而言，属性前缀 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
android:mimeType="MIMEtype"
android:icon="icon_resources"
android:summaryColumn="column_name"
android:detailColumn="column_name">
包含它的文件：
说明：
借助此元素，联系人应用可将自定义数据行的内容显示为原始联系人详细信息的一部分。 的每个 子元素都代表您的同步适配器向 ContactsContract.Data 表添加的某个自定义数据行类型。请为您使用的每个自定义 MIME 类型添加一个 元素。如果您不想显示任何自定义数据行的数据，则无需添加该元素。
属性：
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 表中，有关该表更详细的介绍，请参阅社交流照片部分。
本页面上的内容和代码示例受内容许可部分所述许可的限制。Java 和 OpenJDK 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2023-11-02。
76
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
