Función BluetoothAuthenticateDevice (bluetoothapis.h)

Artículo
03/14/2023

La función BluetoothAuthenticateDevice envía una solicitud de autenticación a un dispositivo Bluetooth remoto.

Nota Al desarrollar para Windows Vista SP2 y Windows 7, se recomienda el uso de BluetoothAuthenticateDeviceEx .

Sintaxis

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

Parámetros

hwndParent

Ventana que va a ser el elemento primario del Asistente para autenticación. Si se establece en NULL, el asistente se quita del escritorio.

hRadio

Identificador de radio local válido o NULL. Si es NULL, se intenta autenticar en todas las radios locales; si alguna radio se realiza correctamente, la llamada de función se realiza correctamente.

pbtbi

Estructura de tipo BLUETOOTH_DEVICE_INFO que contiene el registro del dispositivo Bluetooth que se va a autenticar.

pszPasskey

Un número de identificación personal (PIN) que se usará para la autenticación de dispositivos. Si se establece en NULL, se muestra la interfaz de usuario y el usuario debe seguir el proceso de autenticación proporcionado en la interfaz de usuario. Si pszPasskey no es NULL, no se muestra ninguna interfaz de usuario. Si la clave de acceso no es NULL, debe ser una cadena terminada en NULL. Para obtener más información, vea la sección Comentarios.

ulPasskeyLength

Tamaño, en caracteres, de pszPasskey. El tamaño de pszPasskey debe ser menor o igual que BLUETOOTH_MAX_PASSKEY_SIZE.

Valor devuelto

Devuelve ERROR_SUCCESS tras completarse correctamente.

Los errores comunes se enumeran en la tabla siguiente.

Código devuelto	Descripción
ERROR_CANCELLED	El usuario canceló la operación.
ERROR_INVALID_PARAMETER	La estructura del dispositivo en el parámetro pbtdi no es válida.
ERROR_NO_MORE_ITEMS	El dispositivo al que apunta pbtdi ya está marcado como autenticado.

Comentarios

Algunos dispositivos Bluetooth remotos solo pueden aceptar claves de paso numéricas. No hay ninguna manera de identificar qué dispositivos solo aceptan claves de paso numéricas de antemano.

El proceso de autenticación de Bluetooth tiene dos modos: modo asistente y modo transparente.

El modo de asistente se inicia cuando pszPasskey se establece en NULL y se inicia el Asistente para conexiones Bluetooth. Se pide al usuario que escriba una clave de acceso como paso en el asistente, después de la cual se envía la solicitud de autenticación. La interfaz de usuario muestra si el intento de autenticación se realiza correctamente o se produce un error y proporciona al usuario una oportunidad para volver a intentar una autenticación con errores.

El modo transparente se inicia cuando pszPasskey no es NULL. En modo transparente, la solicitud de autenticación se envía al dispositivo Bluetooth remoto sin mostrar ninguna interfaz de usuario. En modo transparente, el código de estado bluetooth se asigna a un código de error win32; en la tabla siguiente se muestra esta información de asignación.

Código de estado de Bluetooth	Código de error 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

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista, Windows XP con SP2 [solo aplicaciones de escritorio]
Servidor mínimo compatible	No se admite ninguno
Plataforma de destino	Windows
Encabezado	bluetoothapis.h (incluya Bthsdpdef.h, BluetoothAPIs.h)
Library	Bthprops.lib
Archivo DLL	bthprops.cpl