ContactKeyClient

Kotlin |Java

interface ContactKeyClient : HasApiKey

Contact Key API 的客户端。

摘要

公共函数
`Flow<List<E2eeAccountContactKeyParcelable>>`	`@RequiresPermission(value = "android.permission.READ_CONTACTS") getAccountContactKeysFlow(accountIds: List<String>)` 返回账号联系人密钥更新的流。
`Task<E2eeContactKeyListParcelable>`	`@RequiresPermission(value = "android.permission.READ_CONTACTS") getAllE2eeContactKeys(lookupKey: String)` 检索属于对调用方可见的应用的所有端到端加密联系人密钥条目。
`Task<E2eeSelfKeyListParcelable>`	`@RequiresPermission(value = "android.permission.READ_CONTACTS") getAllE2eeSelfKeys()` 返回属于调用方可见的应用的所有端到端加密自密钥条目。
`Task<ImmutableList<E2eeAccountContactKeyParcelable>>`	`@RequiresPermission(value = "android.permission.READ_CONTACTS") getAllOwnerE2eeAccountContactKeys()` 检索属于调用方应用的所有端到端加密账号联系人密钥，无论这些密钥是否与联系人相关联。
`Task<E2eeContactKeyListParcelable>`	`@RequiresPermission(value = "android.permission.READ_CONTACTS") getAllOwnerE2eeContactKeys()` 检索调用方应用的所有端到端加密联系人密钥（适用于所有联系人）。
`Task<ImmutableList<E2eeAccountContactKeyParcelable>>`	`@RequiresPermission(value = "android.permission.READ_CONTACTS") getE2eeAccountKeysForAccount(accountId: String)` 检索属于调用方应用和调用方账号的所有端到端加密联系人密钥条目（涵盖所有联系人）。
`Task<E2eeContactKeyParcelable?>`	`@RequiresPermission(value = "android.permission.READ_CONTACTS") getE2eeContactKey(lookupKey: String, deviceId: String, accountId: String)` 根据 `lookupKey`、`deviceId`、`accountId` 和推断出的调用方软件包名称检索端到端加密联系人密钥条目。
`Task<E2eeSelfKeyParcelable?>`	`@RequiresPermission(value = "android.permission.READ_CONTACTS") getE2eeSelfKey(deviceId: String, accountId: String)` 根据 `deviceId`、`accountId` 和调用方的推断软件包名称，返回端到端加密自密钥条目。
`Task<Int>`	`getMaxKeySizeBytes()` 返回键的最大允许大小（以字节为单位）。
`Task<PendingIntent>`	`getOnboardingIntent( nextActivity: OnboardingNextActivity, lookupKey: String?, packageName: String? )` 返回用于显示新用户引导 Activity 的 intent，并标记此设备上已显示新用户引导。
`Task<E2eeContactKeyListParcelable>`	`@RequiresPermission(value = "android.permission.READ_CONTACTS") getOwnerE2eeContactKeys(lookupKey: String)` 检索属于调用方应用且与给定 `lookupKey` 关联的所有端到端加密联系人密钥条目。
`Task<E2eeSelfKeyListParcelable>`	`@RequiresPermission(value = "android.permission.READ_CONTACTS") getOwnerE2eeSelfKeys()` 返回调用方应用拥有的所有端到端加密自密钥条目。
`Task<PendingIntent>`	`getScanQrCodeIntent(lookupKey: String, skipOnboarding: Boolean)` 返回“扫描二维码”activity 的 intent。
`Task<PendingIntent>`	`getScanQrCodeIntentForAccount(packageName: String, accountId: String)` 返回特定账号的“扫描二维码”activity 的 intent。
`Task<PendingIntent>`	`getShowQrCodeIntent(packageName: String?, skipOnboarding: Boolean)` 返回“显示二维码”activity 的 intent。
`Task<Boolean>`	`isEnabled()` 返回一个任务，无论 API 是否可用，该任务都会成功完成。
`Task<Void>`	`@RequiresPermission(value = "android.permission.READ_CONTACTS") registerAccountContactKeysListener( accountIds: List<String>, listener: OnAccountContactKeysUpdatedListener )` 为账号联系人密钥更新注册监听器。
`Task<Void>`	`@RequiresPermission(value = "android.permission.WRITE_CONTACTS") removeE2eeAccountContactKey(deviceId: String, accountId: String)` 移除属于调用方应用的端到端加密账号联系人密钥条目。
`Task<Void>`	`@RequiresPermission(value = "android.permission.WRITE_CONTACTS") removeE2eeContactKey( lookupKey: String, deviceId: String, accountId: String )` 移除属于调用方应用的端到端加密联系人密钥条目。
`Task<Void>`	`@RequiresPermission(value = "android.permission.WRITE_CONTACTS") removeE2eeSelfKey(deviceId: String, accountId: String)` 根据设备 ID 和调用者的推断软件包名称移除端到端加密自密钥条目。
`Task<Boolean>`	`@CanIgnoreReturnValue unregisterAccountContactKeysListener( listener: OnAccountContactKeysUpdatedListener )` 取消注册账号联系人密钥更新的监听器。
`Task<Void>`	`@RequiresPermission(allOf = ["android.permission.READ_CONTACTS", "android.permission.WRITE_CONTACTS"]) updateAllE2eeAccountKeys(accountKeyInfos: List<E2eeAccountKeyInfo>)` 插入一批账号联系人密钥。
`Task<Void>`	`@RequiresPermission(allOf = ["android.permission.READ_CONTACTS", "android.permission.WRITE_CONTACTS"]) updateOrInsertE2eeContactKey( lookupKey: String, deviceId: String, accountId: String, keyValue: ByteArray )` 在端到端加密联系人密钥表中插入新条目，或更新现有条目。
`Task<Void>`	`@RequiresPermission(allOf = ["android.permission.READ_CONTACTS", "android.permission.WRITE_CONTACTS"]) updateOrInsertE2eeContactKey( lookupKeys: List<String>, deviceId: String, accountId: String, keyValue: ByteArray )` 在端到端加密联系人密钥表中插入新条目，或更新现有条目。
`Task<Void>`	`@RequiresPermission(value = "android.permission.WRITE_CONTACTS") updateOrInsertE2eeSelfKey( deviceId: String, accountId: String, keyValue: ByteArray )` 在端到端加密自密钥表中插入新条目，如果该条目已存在，则更新该条目。

公共函数

getAccountContactKeysFlow

@RequiresPermission(value = "android.permission.READ_CONTACTS")
fun getAccountContactKeysFlow(accountIds: List<String>): Flow<List<E2eeAccountContactKeyParcelable>>

返回账号联系人密钥更新的流。

当提供的任何 accountId 的任何密钥更新、添加或移除时，该流程都会发出。它将针对所提供的 accountId 发出所有密钥的列表，而不仅仅是已更新的密钥。

参数
`accountIds: List<String>`	要监听更新的账号 ID 列表。

返回
`Flow<List<E2eeAccountContactKeyParcelable>>`	一个流，用于在任何密钥更新、添加或移除时，针对所提供的 accountId 发出 `E2eeAccountContactKeyParcelable` 的列表。

抛出
`com.google.android.libraries.sdkcoroutines.flow.CallbackChannelFullException`	如果回调事件的处理速度过慢。

getAllE2eeContactKeys

@RequiresPermission(value = "android.permission.READ_CONTACTS")
fun getAllE2eeContactKeys(lookupKey: String): Task<E2eeContactKeyListParcelable>

检索属于对调用方可见的应用的所有端到端加密联系人密钥条目。密钥将剥离 deviceId、timeUpdated 和 keyValue 数据。

参数
`lookupKey: String`	引用相应联系人的值

返回
`Task<E2eeContactKeyListParcelable>`	一个 `E2eeContactKeyListParcelable`，其中包含端到端加密联系人密钥信息的列表；如果未找到任何密钥，则返回一个空列表。

getAllE2eeSelfKeys

@RequiresPermission(value = "android.permission.READ_CONTACTS")
fun getAllE2eeSelfKeys(): Task<E2eeSelfKeyListParcelable>

返回属于调用方可见的应用的所有端到端加密自密钥条目。密钥将剥离 deviceId、timeUpdated 和 keyValue 数据。

返回
`Task<E2eeSelfKeyListParcelable>`	一个 `E2eeSelfKeyListParcelable`，其中包含端到端加密自密钥信息的列表；如果未找到自密钥，则返回一个空列表。

getAllOwnerE2eeAccountContactKeys

@RequiresPermission(value = "android.permission.READ_CONTACTS")
fun getAllOwnerE2eeAccountContactKeys(): Task<ImmutableList<E2eeAccountContactKeyParcelable>>

检索属于调用方应用的所有端到端加密账号联系人密钥，无论这些密钥是否与联系人相关联。

返回
`Task<ImmutableList<E2eeAccountContactKeyParcelable>>`	包含端到端加密联系人密钥信息的 `E2eeAccountContactKeyParcelable` 对象列表；如果未找到任何密钥，则返回空列表。

getAllOwnerE2eeContactKeys

@RequiresPermission(value = "android.permission.READ_CONTACTS")
fun getAllOwnerE2eeContactKeys(): Task<E2eeContactKeyListParcelable>

检索属于调用方应用的所有端到端加密联系人密钥（适用于所有联系人）。

此方法应仅用于检索至少关联了一个联系人的密钥。如果您需要检索未与任何联系人关联的密钥，请改用 getAllOwnerE2eeAccountContactKeys。

返回
`Task<E2eeContactKeyListParcelable>`	一个 `E2eeContactKeyListParcelable`，其中包含端到端加密联系人密钥信息列表；如果未找到任何密钥，则返回一个空列表。

getE2eeAccountKeysForAccount

@RequiresPermission(value = "android.permission.READ_CONTACTS")
fun getE2eeAccountKeysForAccount(accountId: String): Task<ImmutableList<E2eeAccountContactKeyParcelable>>

检索属于调用方应用和调用方账号的所有端到端加密联系人密钥条目（涵盖所有联系人）。包括未与任何联系人相关联的密钥。

返回
`Task<ImmutableList<E2eeAccountContactKeyParcelable>>`	包含端到端加密联系人密钥信息的 `E2eeAccountContactKeyParcelable` 对象列表；如果未找到任何密钥，则返回空列表。

getE2eeContactKey

@RequiresPermission(value = "android.permission.READ_CONTACTS")
fun getE2eeContactKey(lookupKey: String, deviceId: String, accountId: String): Task<E2eeContactKeyParcelable?>

根据 lookupKey、deviceId、accountId 和推断出的调用方软件包名称检索端到端加密联系人密钥条目。

参数
`lookupKey: String`	引用相应联系人的值
`deviceId: String`	设备的应用指定标识符
`accountId: String`	账号的应用指定标识符

返回
`Task<E2eeContactKeyParcelable?>`	包含联系人密钥信息的 `E2eeContactKeyParcelable`，如果未找到联系人密钥，则返回 null。

getE2eeSelfKey

@RequiresPermission(value = "android.permission.READ_CONTACTS")
fun getE2eeSelfKey(deviceId: String, accountId: String): Task<E2eeSelfKeyParcelable?>

根据 deviceId、accountId 和调用方的推断软件包名称，返回端到端加密自密钥条目。

参数
`deviceId: String`	设备的应用指定标识符
`accountId: String`	账号的应用指定标识符

返回
`Task<E2eeSelfKeyParcelable?>`	包含端到端加密自密钥信息的 `E2eeSelfKeyParcelable`；如果未找到自密钥，则返回 null。

getMaxKeySizeBytes

fun getMaxKeySizeBytes(): Task<Int>

返回键的最大允许大小（以字节为单位）。

getOnboardingIntent

fun getOnboardingIntent(
    nextActivity: OnboardingNextActivity,
    lookupKey: String?,
    packageName: String?
): Task<PendingIntent>

返回用于显示新用户引导 Activity 的 intent，并标记此设备上已显示新用户引导。这需要一个 nextActivity，可以是字符串 show 或 scan。如果值为 scan，则需要提供要扫描的联系人的 lookupKey。

参数
`nextActivity: OnboardingNextActivity`	在初始配置 activity 之后显示的下一个 activity。必须是 `show` 或 `scan`。
`lookupKey: String?`	引用相应联系人的值。如果 `nextActivity` 为 `scan`，则必须提供此值。
`packageName: String?`	与需要密钥的应用相关联的软件包名称（可选）。

getOwnerE2eeContactKeys

@RequiresPermission(value = "android.permission.READ_CONTACTS")
fun getOwnerE2eeContactKeys(lookupKey: String): Task<E2eeContactKeyListParcelable>

检索属于调用方应用且与给定 lookupKey 关联的所有端到端加密联系人密钥条目。

参数
`lookupKey: String`	引用相应联系人的值

返回
`Task<E2eeContactKeyListParcelable>`	一个 `E2eeContactKeyListParcelable`，其中包含端到端加密联系人密钥信息的列表；如果未找到任何密钥，则返回一个空列表。

getOwnerE2eeSelfKeys

@RequiresPermission(value = "android.permission.READ_CONTACTS")
fun getOwnerE2eeSelfKeys(): Task<E2eeSelfKeyListParcelable>

返回调用方应用拥有的所有端到端加密自密钥条目。

返回
`Task<E2eeSelfKeyListParcelable>`	一个 `E2eeSelfKeyListParcelable`，其中包含端到端加密自密钥信息；如果未找到自密钥，则返回一个空列表。

getScanQrCodeIntent

fun getScanQrCodeIntent(lookupKey: String, skipOnboarding: Boolean = false): Task<PendingIntent>

返回“扫描二维码”activity 的 intent。

参数
`lookupKey: String`	引用相应联系人的值
`skipOnboarding: Boolean = false`	目前尚未使用。

getScanQrCodeIntentForAccount

fun getScanQrCodeIntentForAccount(packageName: String, accountId: String): Task<PendingIntent>

返回特定账号的“扫描二维码”activity 的 intent。

参数
`packageName: String`	与用户希望验证的账号相关联的软件包名称
`accountId: String`	与用户希望验证的账号相关联的账号 ID

getShowQrCodeIntent

fun getShowQrCodeIntent(packageName: String?, skipOnboarding: Boolean = false): Task<PendingIntent>

返回“显示二维码”activity 的 intent。

参数
`packageName: String?`	与需要密钥的应用相关联的软件包名称（可选）
`skipOnboarding: Boolean = false`	目前尚未使用。

isEnabled

fun isEnabled(): Task<Boolean>

返回一个任务，无论 API 是否可用，该任务都会成功完成。

如果相应 API 可用，则返回的任务将具有 true 结果，否则将具有 false 结果。

系统会捕获 API 不可用时通常抛出的异常，并改为返回成功返回 false 的任务。

registerAccountContactKeysListener

@RequiresPermission(value = "android.permission.READ_CONTACTS")
fun registerAccountContactKeysListener(
    accountIds: List<String>,
    listener: OnAccountContactKeysUpdatedListener
): Task<Void>

为账号联系人密钥更新注册监听器。

当提供的任何 accountId 的任何密钥更新、添加或移除时，系统都会调用该监听器。系统将使用所提供 accountId 的所有密钥（而不仅仅是已更新的密钥）来调用该函数。

参数
`accountIds: List<String>`	要注册监听器的账号 ID 列表。
`listener: OnAccountContactKeysUpdatedListener`	要注册的监听器。

removeE2eeAccountContactKey

@RequiresPermission(value = "android.permission.WRITE_CONTACTS")
fun removeE2eeAccountContactKey(deviceId: String, accountId: String): Task<Void>

移除属于调用方应用的端到端加密账号联系人密钥条目。

参数
`deviceId: String`	设备的应用指定标识符
`accountId: String`	账号的应用指定标识符

removeE2eeContactKey

@RequiresPermission(value = "android.permission.WRITE_CONTACTS")
fun removeE2eeContactKey(
    lookupKey: String,
    deviceId: String,
    accountId: String
): Task<Void>

移除属于调用方应用的端到端加密联系人密钥条目。

参数
`lookupKey: String`	引用相应联系人的值
`deviceId: String`	设备的应用指定标识符
`accountId: String`	账号的应用指定标识符

removeE2eeSelfKey

@RequiresPermission(value = "android.permission.WRITE_CONTACTS")
fun removeE2eeSelfKey(deviceId: String, accountId: String): Task<Void>

根据设备 ID 和调用者的推断软件包名称移除端到端加密自密钥条目。

参数
`deviceId: String`	设备的应用指定标识符
`accountId: String`	账号的应用指定标识符

unregisterAccountContactKeysListener

@CanIgnoreReturnValue
fun unregisterAccountContactKeysListener(
    listener: OnAccountContactKeysUpdatedListener
): Task<Boolean>

取消注册账号联系人密钥更新的监听器。

参数
`listener: OnAccountContactKeysUpdatedListener`	要取消注册的监听器。

updateAllE2eeAccountKeys

@RequiresPermission(allOf = ["android.permission.READ_CONTACTS", "android.permission.WRITE_CONTACTS"])
fun updateAllE2eeAccountKeys(accountKeyInfos: List<E2eeAccountKeyInfo>): Task<Void>

插入一批账号联系人密钥。

行为与 updateOrInsertE2eeContactKey 类似，但允许一次插入/更新多个键。每个键都插入在自己的事务中，因此即使任务抛出异常，也可能会插入一些键。

客户端可以选择重新发送整个批次来处理临时性故障，因为此 API 不会影响已插入密钥的状态。

对于每个键，如果提供了 lookupKey 但未提供联系人基本信息（displayName、phoneNumber、emailAddress），此 API 还会尝试从联系人提供程序检索联系人的姓名、电话号码和电子邮件地址。在检索密钥时，联系人管理应用应使用此信息来确保密钥仅用于其预定用途的联系人。

Android 密钥验证应用会将此信息存储在设备上，并且仅向持有 READ_CONTACTS 权限的 API 调用方公开此信息。

如果未为密钥提供 lookupKey，此 API 将存储未与任何联系人关联的密钥。

参数
`accountKeyInfos: List<E2eeAccountKeyInfo>`	包含端到端加密联系人密钥信息的 `E2eeAccountKeyInfo` 对象列表。

updateOrInsertE2eeContactKey

@RequiresPermission(allOf = ["android.permission.READ_CONTACTS", "android.permission.WRITE_CONTACTS"])
fun updateOrInsertE2eeContactKey(
    lookupKey: String,
    deviceId: String,
    accountId: String,
    keyValue: ByteArray
): Task<Void>

在端到端加密联系人密钥表中插入新条目，或更新现有条目。插入/更新的端到端加密联系人密钥归调用方应用所有。

此 API 还会存储来自“联系人提供程序”的联系人姓名、电话号码和电子邮件地址，以及密钥。在检索密钥时，联系人管理应用应使用此信息来确保密钥仅用于其预定用途的联系人。

Android 密钥验证应用会将此信息存储在设备上，并且仅向持有 READ_CONTACTS 权限的 API 调用方公开此信息。

参数
`lookupKey: String`	引用相应联系人的值
`deviceId: String`	设备的应用指定标识符
`accountId: String`	账号的应用指定标识符
`keyValue: ByteArray`	密钥的原始字节（最大大小为 `getMaxKeySizeBytes` 字节）

updateOrInsertE2eeContactKey

@RequiresPermission(allOf = ["android.permission.READ_CONTACTS", "android.permission.WRITE_CONTACTS"])
fun updateOrInsertE2eeContactKey(
    lookupKeys: List<String>,
    deviceId: String,
    accountId: String,
    keyValue: ByteArray
): Task<Void>

在端到端加密联系人密钥表中插入新条目，或更新现有条目。插入/更新的端到端加密联系人密钥归调用方应用所有。

对于提供的每个查找键，此 API 还会将联系人的姓名、电话号码和电子邮件地址（来自“联系人提供程序”）与该键一起存储。在检索密钥时，联系人管理应用应使用此信息来确保密钥仅用于其预定用途的联系人。

Android 密钥验证应用会将此信息存储在设备上，并且仅向持有 READ_CONTACTS 权限的 API 调用方公开此信息。

如果查找键列表为空，此 API 将存储未与任何联系人关联的键。

使用一个或多个查找键调用此 API 将更新键元数据，以将其与提供的联系人相关联，但不会移除未在列表中提供的联系人的任何现有关联。如需移除联系人与密钥之间的关联，请使用相应的查找键调用 removeE2eeContactKey。

参数
`lookupKeys: List<String>`	可能为空的 CP2 查找键列表，用于引用与该键关联的联系人
`deviceId: String`	设备的应用指定标识符
`accountId: String`	账号的应用指定标识符
`keyValue: ByteArray`	密钥的原始字节（最大大小为 `getMaxKeySizeBytes` 字节）

updateOrInsertE2eeSelfKey

@RequiresPermission(value = "android.permission.WRITE_CONTACTS")
fun updateOrInsertE2eeSelfKey(
    deviceId: String,
    accountId: String,
    keyValue: ByteArray
): Task<Void>

在端到端加密自密钥表中插入新条目，如果该条目已存在，则更新该条目。

参数
`deviceId: String`	设备的应用指定标识符
`accountId: String`	账号的应用指定标识符
`keyValue: ByteArray`	密钥的原始字节（最大大小为 `getMaxKeySizeBytes` 字节）