Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

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 *pbtdi,
  PWCHAR 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.

pbtdi

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 codeDescription
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 codeWin32 error code
BTH_ERROR_SUCCESSERROR_SUCCESS
BTH_ERROR_NO_CONNECTIONERROR_DEVICE_NOT_CONNECTED
BTH_ERROR_PAGE_TIMEOUTWAIT_TIMEOUT
BTH_ERROR_HARDWARE_FAILUREERROR_GEN_FAILURE
BTH_ERROR_AUTHENTICATION_FAILUREERROR_NOT_AUTHENTICATED
BTH_ERROR_MEMORY_FULLERROR_NOT_ENOUGH_MEMORY
BTH_ERROR_CONNECTION_TIMEOUTWAIT_TIMEOUT
BTH_ERROR_LMP_RESPONSE_TIMEOUTWAIT_TIMEOUT
BTH_ERROR_MAX_NUMBER_OF_CONNECTIONSERROR_REQ_NOT_ACCEP
BTH_ERROR_PAIRING_NOT_ALLOWEDERROR_ACCESS_DENIED
BTH_ERROR_UNSPECIFIED_ERRORERROR_NOT_READY
BTH_ERROR_LOCAL_HOST_TERMINATED_CONNECTIONERROR_VC_DISCONNECTED

 

Requirements

Minimum supported client

Windows Vista, Windows XP with SP2 [desktop apps only]

Minimum supported server

None supported

Header

BluetoothAPIs.h (include Bthsdpdef.h or BluetoothAPIs.h)

Library

Bthprops.lib

DLL

Bthprops.dll

See also

BluetoothAuthenticateDeviceEx
BluetoothAuthenticateMultipleDevices
BluetoothEnableDiscovery
BluetoothEnableIncomingConnections
BluetoothIsConnectable
BluetoothIsDiscoverable
BluetoothRegisterForAuthentication
BluetoothSendAuthenticationResponse
BluetoothUnregisterAuthentication
BLUETOOTH_DEVICE_INFO

 

 

Community Additions

Show:
© 2014 Microsoft