BluetoothAuthenticateDevice function

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

   
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.dll

See Also

BLUETOOTH_DEVICE_INFO

BluetoothAuthenticateDeviceEx

BluetoothAuthenticateMultipleDevices

BluetoothEnableDiscovery

BluetoothEnableIncomingConnections

BluetoothIsConnectable

BluetoothIsDiscoverable

BluetoothRegisterForAuthentication

BluetoothSendAuthenticationResponse

BluetoothUnregisterAuthentication