Fonction BluetoothAuthenticateDevice (bluetoothapis.h)

Article
08/22/2023

La fonction BluetoothAuthenticateDevice envoie une demande d’authentification à un appareil Bluetooth distant.

Note Lors du développement pour Windows Vista SP2 et Windows 7, l’utilisation de BluetoothAuthenticateDeviceEx est recommandée.

Syntaxe

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

Paramètres

hwndParent

Fenêtre qui doit être le parent de l’Assistant Authentification. Si la valeur est NULL, l’Assistant est supprimé du bureau.

hRadio

Un handle radio local valide, ou NULL. Si la valeur est NULL, l’authentification est tentée sur toutes les radios locales ; si une radio réussit, l’appel de fonction réussit.

pbtbi

Structure de type BLUETOOTH_DEVICE_INFO qui contient l’enregistrement de l’appareil Bluetooth à authentifier.

pszPasskey

Un numéro d’identification personnel (PIN) à utiliser pour l’authentification de l’appareil. Si la valeur est NULL, l’interface utilisateur s’affiche et l’utilisateur doit suivre le processus d’authentification fourni dans l’interface utilisateur. Si pszPasskey n’a pas la valeur NULL, aucune interface utilisateur n’est affichée. Si la clé d’accès n’est pas NULL, il doit s’agir d’une chaîne terminée par NULL. Pour plus d'informations, consultez la section Notes.

ulPasskeyLength

Taille, en caractères, de pszPasskey. La taille de pszPasskey doit être inférieure ou égale à BLUETOOTH_MAX_PASSKEY_SIZE.

Valeur retournée

Retourne ERROR_SUCCESS en cas de réussite de l’exécution.

Les erreurs courantes sont répertoriées dans le tableau suivant.

Code de retour	Description
ERROR_CANCELLED	L’utilisateur a annulé l’opération.
ERROR_INVALID_PARAMETER	La structure de l’appareil dans le paramètre pbtdi n’est pas valide.
ERROR_NO_MORE_ITEMS	L’appareil pointé par pbtdi est déjà marqué comme authentifié.

Remarques

Certains appareils Bluetooth distants peuvent uniquement accepter des clés d’accès numériques. Il n’existe aucun moyen d’identifier les appareils qui acceptent uniquement les clés d’accès numériques à l’avance.

Le processus d’authentification Bluetooth a deux modes : le mode Assistant et le mode Transparent.

Le mode Assistant est démarré lorsque pszPasskey est défini sur NULL et que l’Assistant Connexion Bluetooth est démarré. L’utilisateur est invité à entrer une clé d’accès en tant qu’étape dans l’Assistant, après quoi la demande d’authentification est envoyée. L’interface utilisateur indique si la tentative d’authentification réussit ou échoue, et offre à l’utilisateur la possibilité de réessayer une authentification ayant échoué.

Le mode transparent est démarré lorsque pszPasskey n’a pas la valeur NULL. En mode transparent, la demande d’authentification est envoyée à l’appareil Bluetooth distant sans afficher d’interface utilisateur. En mode transparent, le code de status Bluetooth est mappé à un code d’erreur Win32 ; le tableau suivant répertorie ces informations de mappage.

Code status Bluetooth	Code d’erreur 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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista, Windows XP avec SP2 [applications de bureau uniquement]
Serveur minimal pris en charge	Aucun pris en charge
Plateforme cible	Windows
En-tête	bluetoothapis.h (inclure Bthsdpdef.h, BluetoothAPIs.h)
Bibliothèque	Bthprops.lib
DLL	bthprops.cpl