Функция BluetoothAuthenticateDevice (bluetoothapis.h)

Статья
03/14/2023

Функция BluetoothAuthenticateDevice отправляет запрос проверки подлинности на удаленное устройство Bluetooth.

Примечание При разработке для Windows Vista с пакетом обновления 2 (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 , содержащая запись устройства Bluetooth для проверки подлинности.

pszPasskey

Личный идентификационный номер (ПИН-код), используемый для проверки подлинности устройства. Если задано значение 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 , уже помечено как прошедшее проверку подлинности.

Некоторые удаленные устройства Bluetooth могут принимать только числовые ключи доступа. Невозможно определить, какие устройства принимают только числовые ключи доступа заранее.

Процесс проверки подлинности Bluetooth имеет два режима: режим мастера и прозрачный режим.

Режим мастера запускается, когда для pszPasskey задано значение NULL, а мастер подключений Bluetooth запускается. Пользователю будет предложено ввести ключ доступа в качестве шага в мастере, после чего отправляется запрос проверки подлинности. В пользовательском интерфейсе отображается, была ли попытка проверки подлинности успешной или неудачной, и пользователю предоставляется возможность повторно выполнить проверку подлинности, которая завершилась сбоем.

Прозрачный режим запускается, если параметр pszPasskey не имеет значения NULL. В прозрачном режиме запрос проверки подлинности отправляется на удаленное устройство Bluetooth без отображения пользовательского интерфейса. В прозрачном режиме код состояния Bluetooth сопоставляется с кодом ошибки Win32; В следующей таблице перечислены эти сведения о сопоставлении.

Код состояния Bluetooth	Код ошибки 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 с пакетом обновления 2 (SP2) [только классические приложения]
Минимальная версия сервера	Ни одна версия не поддерживается
Целевая платформа	Windows
Header	bluetoothapis.h (включая Bthsdpdef.h, BluetoothAPIs.h)
Библиотека	Bthprops.lib
DLL	bthprops.cpl