BluetoothAuthenticateDevice function (bluetoothapis.h)

Article
05/24/2022

The BluetoothAuthenticateDevice function sends an authentication request to a remote Bluetooth device.

Note When developing for Windows Vista SP2 and Windows 7 the use of BluetoothAuthenticateDeviceEx is recommended.

Syntax

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

Parameters

hwndParent

A window to be the parent of the Authentication wizard. If set to NULL, the wizard is removed from the desktop.

hRadio

A valid local radio handle, or NULL. If NULL, authentication is attempted on all local radios; if any radio succeeds, the function call succeeds.

pbtbi

A structure of type BLUETOOTH_DEVICE_INFO that contains the record of the Bluetooth device to be authenticated.

pszPasskey

A Personal Identification Number (PIN) to be used for device authentication. If set to NULL, the user interface is displayed and the user must follow the authentication process provided in the user interface. If pszPasskey is not NULL, no user interface is displayed. If the passkey is not NULL, it must be a NULL-terminated string. For more information, see the Remarks section.

ulPasskeyLength

The size, in characters, of pszPasskey. The size of pszPasskey must be less than or equal to BLUETOOTH_MAX_PASSKEY_SIZE.

Return value

Returns ERROR_SUCCESS upon successful completion.

Common errors are listed in the following table.

Return code	Description
ERROR_CANCELLED	The user canceled the operation.
ERROR_INVALID_PARAMETER	The device structure in the pbtdi parameter is not valid.
ERROR_NO_MORE_ITEMS	The device pointed to by pbtdi is already marked as authenticated.

Remarks

Some remote Bluetooth devices can only accept numeric passkeys. There is no way to identify which devices only accept numeric passkeys in advance.

The Bluetooth authentication process has two modes: Wizard mode and Transparent mode.

Wizard mode is started when pszPasskey is set to NULL, and the Bluetooth Connection Wizard is started. The user is prompted to enter a passkey as a step in the wizard, after which the authentication request is sent. The user interface displays whether the authentication attempt succeeds or fails, and provides the user with an opportunity to reattempt a failed authentication.

Transparent mode is started when pszPasskey is not NULL. In Transparent mode the authentication request is sent to the remote Bluetooth device without displaying any user interface. In Transparent mode, the Bluetooth status code is mapped to a Win32 error code; the following table lists this mapping information.

Bluetooth status code	Win32 error code
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

Requirements

Requirement	Value
Minimum supported client	Windows Vista, Windows XP with SP2 [desktop apps only]
Minimum supported server	None supported
Target Platform	Windows
Header	bluetoothapis.h (include Bthsdpdef.h, BluetoothAPIs.h)
Library	Bthprops.lib
DLL	bthprops.cpl