BluetoothAuthenticateDevice-Funktion (bluetoothapis.h)

Artikel
02/02/2023
2 Minuten Lesedauer

Die BluetoothAuthenticateDevice-Funktion sendet eine Authentifizierungsanforderung an ein Remote-Bluetooth-Gerä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 Element des Authentifizierungs-Assistenten sein soll. Wenn er auf NULL festgelegt ist, wird der Assistent aus dem Desktop entfernt.

hRadio

Ein gültiger lokaler Funkpunkt oder NULL. Wenn NULL versucht wird, wird die Authentifizierung auf allen lokalen Radios versucht; Wenn ein Funk erfolgreich ist, ist der Funktionsaufruf erfolgreich.

pbtbi

Eine Struktur vom Typ BLUETOOTH_DEVICE_INFO , die den Datensatz des bluetooth-Geräts enthält, das authentifiziert werden soll.

pszPasskey

Eine persönliche Identifikationsnummer (PIN), die für die Geräteauthentifizierung verwendet werden soll. Wenn die Benutzeroberfläche auf NULL festgelegt ist, wird die Benutzeroberfläche angezeigt, und der Benutzer muss dem in der Benutzeroberfläche bereitgestellten Authentifizierungsprozess folgen. Wenn pszPasskey nicht NULL ist, wird keine Benutzeroberfläche angezeigt. Wenn der Schlüssel nicht NULL ist, muss es sich um eine NULL-beendete Zeichenfolge handelt. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

ulPasskeyLength

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

Rückgabewert

Gibt ERROR_SUCCESS nach erfolgreicher Fertigstellung zurück.

Häufige Fehler werden 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.

Bemerkungen

Einige Remote-Bluetooth-Geräte können nur numerische Passkeys akzeptieren. Es gibt keine Möglichkeit zu identifizieren, welche Geräte nur numerische Passkeys 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 wird gestartet. Der Benutzer wird aufgefordert, einen Passkey 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 der Benutzer erhält eine Möglichkeit, eine fehlgeschlagene Authentifizierung erneut zu aktualisieren.

Transparenter Modus wird gestartet, wenn pszPasskey nicht NULL ist. Im transparenten Modus wird die Authentifizierungsanforderung an das Remote-Bluetooth-Gerät gesendet, ohne eine Benutzeroberfläche anzuzeigen. Im transparenten Modus wird der Bluetooth-Statuscode einem Win32-Fehlercode zugeordnet; In der folgenden Tabelle sind diese Zuordnungsinformationen aufgeführt.

Bluetooth-Statuscode	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


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