BluetoothAuthenticateDevice-Funktion (bluetoothapis.h)

Artikel
02/23/2024

Die BluetoothAuthenticateDevice-Funktion sendet eine Authentifizierungsanforderung an ein Bluetooth-Remotegerät.

Hinweis Bei der Entwicklung für Windows Vista SP2 und Windows 7 wird die Verwendung von BluetoothAuthenticateDeviceEx empfohlen.

Syntax

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

Parameter

hwndParent

Ein Fenster, das das übergeordnete Fenster des Authentifizierungs-Assistenten sein soll. Wenn dieser Wert auf NULL festgelegt ist, wird der Assistent vom Desktop entfernt.

hRadio

Ein gültiges lokales Funkhandle oder NULL. Wenn NULL, wird die Authentifizierung für alle lokalen Funkgeräte versucht. Wenn ein Funk erfolgreich ist, ist der Funktionsaufruf erfolgreich.

pbtbi

Eine Struktur vom Typ BLUETOOTH_DEVICE_INFO , die den Datensatz des zu authentifizierden Bluetooth-Geräts enthält.

pszPasskey

Eine persönliche Identifikationsnummer (PIN), die für die Geräteauthentifizierung verwendet werden soll. Wenn dieser Wert auf NULL festgelegt ist, wird die Benutzeroberfläche angezeigt, und der Benutzer muss den in der Benutzeroberfläche angegebenen Authentifizierungsprozess befolgen. Wenn pszPasskey nicht NULL ist, wird keine Benutzeroberfläche angezeigt. Wenn der Kennungsschlüssel nicht NULL ist, muss es sich um eine MIT NULL beendete Zeichenfolge handeln. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

ulPasskeyLength

Die Größe von pszPasskey in Zeichen. Die Größe von pszPasskey muss kleiner oder gleich BLUETOOTH_MAX_PASSKEY_SIZE sein.

Rückgabewert

Gibt nach erfolgreichem Abschluss ERROR_SUCCESS zurück.

Häufige Fehler sind in der folgenden Tabelle aufgeführt.

Rückgabecode	Beschreibung
ERROR_CANCELLED	Der Benutzer hat den Vorgang abgebrochen.
ERROR_INVALID_PARAMETER	Die Gerätestruktur im pbtdi-Parameter ist ungültig.
ERROR_NO_MORE_ITEMS	Das Gerät, auf das pbtdi verweist, ist bereits als authentifiziert gekennzeichnet.

Hinweise

Einige Bluetooth-Remotegeräte können nur numerische Schlüssel akzeptieren. Es gibt keine Möglichkeit zu ermitteln, welche Geräte nur numerische Schlüssel im Voraus akzeptieren.

Der Bluetooth-Authentifizierungsprozess verfügt über zwei Modi: Assistentenmodus und Transparenter Modus.

Der Assistentmodus wird gestartet, wenn pszPasskey auf NULL festgelegt ist und der Bluetooth-Verbindungs-Assistent gestartet wird. Der Benutzer wird aufgefordert, einen Schlüssel als Schritt im Assistenten einzugeben, nach dem die Authentifizierungsanforderung gesendet wird. Die Benutzeroberfläche zeigt an, ob der Authentifizierungsversuch erfolgreich ist oder fehlschlägt, und bietet dem Benutzer die Möglichkeit, eine fehlgeschlagene Authentifizierung erneut zu wiederholen.

Der transparente Modus wird gestartet, wenn pszPasskey nicht NULL ist. Im transparenten Modus wird die Authentifizierungsanforderung an das Bluetooth-Remotegerät gesendet, ohne dass eine Benutzeroberfläche angezeigt wird. Im transparenten Modus wird der Bluetooth-status Code einem Win32-Fehlercode zugeordnet. In der folgenden Tabelle sind diese Zuordnungsinformationen aufgeführt.

Bluetooth-status-Code	Win32-Fehlercode
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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista, Windows XP mit SP2 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Nicht unterstützt
Zielplattform	Windows
Kopfzeile	bluetoothapis.h (include Bthsdpdef.h, BluetoothAPIs.h)
Bibliothek	Bthprops.lib
DLL	bthprops.cpl