BluetoothAuthenticateDevice-Funktion (bluetoothapis.h)

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

Weitere Informationen

BLUETOOTH_DEVICE_INFO

BluetoothAuthenticateDeviceEx

BluetoothAuthenticateMultipleDevices

BluetoothEnableDiscovery

BluetoothEnableIncomingConnections

BluetoothIsConnectable

BluetoothIsDiscoverable

BluetoothRegisterForAuthentication

BluetoothSendAuthenticationResponse

BluetoothUnregisterAuthentication