BluetoothAuthenticateDevice 函数 (bluetoothapis.h)

项目
08/22/2023

BluetoothAuthenticateDevice 函数将身份验证请求发送到远程蓝牙设备。

注意针对 Windows Vista SP2 和 Windows 7 进行开发时，建议使用 BluetoothAuthenticateDeviceEx 。

语法

DWORD BluetoothAuthenticateDevice(
  HWND                  hwndParent,
  HANDLE                hRadio,
  BLUETOOTH_DEVICE_INFO *pbtbi,
  PWSTR                 pszPasskey,
  ULONG                 ulPasskeyLength
);

参数

hwndParent

作为身份验证向导的父级的窗口。如果设置为 NULL，则会从桌面中删除向导。

hRadio

有效的本地单选句柄，或 NULL。如果 为 NULL，则尝试在所有本地无线电上进行身份验证;如果任何无线电成功，则函数调用成功。

pbtbi

类型为 BLUETOOTH_DEVICE_INFO 的结构，包含要进行身份验证的蓝牙设备的记录。

pszPasskey

个人标识号 (PIN) 用于设备身份验证。如果设置为 NULL，则显示用户界面，用户必须遵循用户界面中提供的身份验证过程。如果 pszPasskey 不为 NULL，则不显示任何用户界面。如果密钥不是 NULL，则它必须是 以 NULL 结尾的字符串。有关详细信息，请参见“备注”部分。

ulPasskeyLength

pszPasskey 的大小（以字符为单位）。 pszPasskey 的大小必须小于或等于 BLUETOOTH_MAX_PASSKEY_SIZE。

返回值

成功完成后返回 ERROR_SUCCESS 。

下表列出了常见错误。

返回代码	说明
ERROR_CANCELLED	用户取消了操作。
ERROR_INVALID_PARAMETER	pbtdi 参数中的设备结构无效。
ERROR_NO_MORE_ITEMS	pbtdi 指向的设备已标记为已经过身份验证。

注解

某些远程蓝牙设备只能接受数字密钥。无法提前确定哪些设备仅接受数字密钥。

蓝牙身份验证过程有两种模式：向导模式和透明模式。

当 pszPasskey 设置为 NULL 并启动蓝牙连接向导时，将启动向导模式。系统会提示用户输入密钥作为向导中的步骤，然后发送身份验证请求。用户界面显示身份验证尝试是成功还是失败，并为用户提供重新尝试失败身份验证的机会。

当 pszPasskey 不为 NULL 时，将启动透明模式。在透明模式下，身份验证请求将发送到远程蓝牙设备，而不会显示任何用户界面。在透明模式下，蓝牙状态代码映射到 Win32 错误代码;下表列出了此映射信息。

蓝牙状态代码	Win32 错误代码
BTH_ERROR_SUCCESS	ERROR_SUCCESS
BTH_ERROR_NO_CONNECTION	ERROR_DEVICE_NOT_CONNECTED
BTH_ERROR_PAGE_TIMEOUT	WAIT_TIMEOUT
BTH_ERROR_HARDWARE_FAILURE	ERROR_GEN_FAILURE
BTH_ERROR_AUTHENTICATION_FAILURE	ERROR_NOT_AUTHENTICATED
BTH_ERROR_MEMORY_FULL	ERROR_NOT_ENOUGH_MEMORY
BTH_ERROR_CONNECTION_TIMEOUT	WAIT_TIMEOUT
BTH_ERROR_LMP_RESPONSE_TIMEOUT	WAIT_TIMEOUT
BTH_ERROR_MAX_NUMBER_OF_CONNECTIONS	ERROR_REQ_NOT_ACCEP
BTH_ERROR_PAIRING_NOT_ALLOWED	ERROR_ACCESS_DENIED
BTH_ERROR_UNSPECIFIED_ERROR	ERROR_NOT_READY
BTH_ERROR_LOCAL_HOST_TERMINATED_CONNECTION	ERROR_VC_DISCONNECTED

要求

要求	值
最低受支持的客户端	Windows Vista、Windows XP 和 SP2 [仅限桌面应用]
最低受支持的服务器	无受支持的版本
目标平台	Windows
标头	bluetoothapis.h (包括 Bthsdpdef.h、BluetoothAPIs.h)
Library	Bthprops.lib
DLL	bthprops.cpl