Funzione BluetoothAuthenticateDevice (bluetoothapis.h)

Articolo
03/14/2023

La funzione BluetoothAuthenticateDevice invia una richiesta di autenticazione a un dispositivo Bluetooth remoto.

Nota Quando si sviluppa per Windows Vista SP2 e Windows 7, è consigliabile usare BluetoothAuthenticateDeviceEx .

Sintassi

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

Parametri

hwndParent

Finestra da inserire nell'elemento padre della procedura guidata Autenticazione. Se impostato su NULL, la procedura guidata viene rimossa dal desktop.

hRadio

Handle di radio locale valido o NULL. Se NULL, l'autenticazione viene tentata su tutte le radio locali; se una radio ha esito positivo, la chiamata alla funzione ha esito positivo.

pbtbi

Struttura di tipo BLUETOOTH_DEVICE_INFO contenente il record del dispositivo Bluetooth da autenticare.

pszPasskey

Un PIN (Personal Identification Number) da usare per l'autenticazione del dispositivo. Se impostato su NULL, l'interfaccia utente viene visualizzata e l'utente deve seguire il processo di autenticazione fornito nell'interfaccia utente. Se pszPasskey non è NULL, non viene visualizzata alcuna interfaccia utente. Se la passkey non è NULL, deve essere una stringa con terminazione NULL. Per altre informazioni, vedere la sezione Osservazioni.

ulPasskeyLength

Dimensioni, in caratteri, di pszPasskey. Le dimensioni di pszPasskey devono essere inferiori o uguali a BLUETOOTH_MAX_PASSKEY_SIZE.

Valore restituito

Restituisce ERROR_SUCCESS al completamento corretto.

Gli errori comuni sono elencati nella tabella seguente.

Codice restituito	Descrizione
ERROR_CANCELLED	L'utente ha annullato l'operazione.
ERROR_INVALID_PARAMETER	La struttura del dispositivo nel parametro pbtdi non è valida.
ERROR_NO_MORE_ITEMS	Il dispositivo a cui fa riferimento pbtdi è già contrassegnato come autenticato.

Commenti

Alcuni dispositivi Bluetooth remoti possono accettare solo passkey numerici. Non è possibile identificare in anticipo i dispositivi che accettano solo passkey numerici.

Il processo di autenticazione Bluetooth ha due modalità: modalità procedura guidata e modalità Trasparente.

La modalità guidata viene avviata quando pszPasskey è impostato su NULL e viene avviata la Procedura guidata connessione Bluetooth. L'utente viene richiesto di immettere una passkey come passaggio della procedura guidata, dopo il quale viene inviata la richiesta di autenticazione. L'interfaccia utente visualizza se il tentativo di autenticazione ha esito positivo o non riesce e fornisce all'utente l'opportunità di ripetere l'autenticazione non riuscita.

La modalità trasparente viene avviata quando pszPasskey non è NULL. In modalità trasparente la richiesta di autenticazione viene inviata al dispositivo Bluetooth remoto senza visualizzare alcuna interfaccia utente. In modalità Trasparente il codice di stato Bluetooth viene mappato a un codice di errore Win32; nella tabella seguente sono elencate queste informazioni di mapping.

Codice di stato Bluetooth	Codice di errore 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

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista, Windows XP con SP2 [solo app desktop]
Server minimo supportato	Nessuno supportato
Piattaforma di destinazione	Windows
Intestazione	bluetoothapis.h (includere Bthsdpdef.h, BluetoothAPIs.h)
Libreria	Bthprops.lib
DLL	bthprops.cpl