Funzione WlanHostedNetworkQuerySecondaryKey (wlanapi.h)

Articolo
03/15/2023

La funzione WlanHostedNetworkQuerySecondaryKey esegue una query sulla chiave di sicurezza secondaria configurata per essere utilizzata dalla rete ospitata wireless.

Sintassi

DWORD WlanHostedNetworkQuerySecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [out]           PDWORD                      pdwKeyLength,
  [out]           PUCHAR                      *ppucKeyData,
  [out]           PBOOL                       pbIsPassPhrase,
  [out]           PBOOL                       pbPersistent,
  [out, optional] PWLAN_HOSTED_NETWORK_REASON pFailReason,
                  PVOID                       pvReserved
);

Parametri

[in] hClientHandle

Handle di sessione del client, restituito da una chiamata precedente alla funzione WlanOpenHandle .

[out] pdwKeyLength

Puntatore a un valore che specifica il numero di byte di dati validi nella matrice di dati chiave a cui punta il parametro ppucKeyData , se la chiamata alla funzione WlanHostedNetworkQuerySecondaryKey ha esito positivo.

Questa lunghezza della chiave include la terminazione '\0' se la chiave è una passphrase.

[out] ppucKeyData

Puntatore a un valore che riceve un puntatore al buffer restituito con i dati della chiave di sicurezza secondaria, se la chiamata alla funzione WlanHostedNetworkQuerySecondaryKey ha esito positivo.

[out] pbIsPassPhrase

Puntatore a un valore booleano che indica se la matrice di dati chiave a cui punta il parametro ppucKeyData è in formato passphrase.

Se questo parametro è TRUE, la matrice di dati chiave è in formato passphrase. Se questo parametro è FALSE, la matrice di dati chiave non è in formato passphrase.

[out] pbPersistent

Puntatore a un valore booleano che indica se la matrice di dati chiave a cui punta il parametro ppucKeyData deve essere archiviata e riutilizzata in un secondo momento oppure è solo per un uso monouso.

Se questo parametro è TRUE, la matrice di dati chiave deve essere archiviata e riutilizzata in un secondo momento. Se questo parametro è FALSE, la matrice di dati chiave è solo per uso monouso.

[out, optional] pFailReason

Puntatore facoltativo a un valore che riceve il motivo dell'errore, se la chiamata alla funzione WlanHostedNetworkSetSecondaryKey ha esito negativo. I valori possibili per il motivo dell'errore provengono dal tipo di enumerazione WLAN_HOSTED_NETWORK_REASON definito nel file di intestazione Wlanapi.h .

pvReserved

Riservato per utilizzi futuri. Questo parametro deve essere NULL.

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene ERROR_SUCCESS.

Se la funzione ha esito negativo, il valore restituito può essere uno dei codici restituiti seguenti.

Codice restituito	Descrizione
ERROR_INVALID_HANDLE	Handle non valido. Questo errore viene restituito se l'handle specificato nel parametro hClientHandle non è stato trovato nella tabella handle.
ERROR_INVALID_PARAMETER	Un parametro non è corretto. Questo errore viene restituito se si verifica una delle condizioni seguenti: hClientHandle è NULL. pdwKeyLength è NULL. ppucKeyData è NULL o non valido. pbIsPassPhrase è NULL o non valido. pbPersistent è NULL. pvReserved non è NULL.
ERROR_INVALID_STATE	La risorsa non è nello stato corretto per eseguire l'operazione richiesta. Ciò può verificarsi se la rete ospitata wireless è in corso di arresto.
ERROR_OUTOFMEMORY	Memoria disponibile insufficiente per completare l'operazione.
ERROR_SERVICE_NOT_ACTIVE	Il servizio non è stato avviato. Questo errore viene restituito se il servizio WLAN AutoConfig non è in esecuzione.
Altri	Vari codici di errore RPC e altri. Usare FormatMessage per ottenere la stringa del messaggio per l'errore restituito.

Commenti

La funzione WlanHostedNetworkQuerySecondaryKey è un'estensione alle API wireless native aggiunte per supportare la rete ospitata wireless in Windows 7 e in Windows Server 2008 R2 con il servizio LAN wireless installato.

Un'applicazione client chiama la funzione WlanHostedNetworkQuerySecondaryKey per eseguire una query sulla chiave di sicurezza secondaria che verrà usata dalla rete ospitata wireless. Questa funzione restituirà le informazioni sulla chiave, inclusi i dati chiave, la lunghezza della chiave, se si tratta di una passphrase e se è persistente o monouso. Questa funzione non modifica lo stato o le proprietà della rete ospitata wireless.

La chiave di sicurezza secondaria è una passphrase se il valore a cui punta il parametro pbIsPassPhrase è TRUE. La chiave di sicurezza secondaria è una chiave binaria se il valore a cui punta il parametro pbIsPassPhrase è FALSE.

La chiave di sicurezza secondaria restituita nel buffer a cui punta il parametro ppucKeyData viene usata con l'autenticazione WPA2-Personal ed è in uno dei formati seguenti:

Passphrase chiave costituita da una matrice di caratteri ASCII da 8 a 63 caratteri. Il valore a cui punta il parametro pdwKeyLength include la terminazione '\0' nella passphrase. Il valore a cui punta il parametro pdwKeyLength deve essere compreso nell'intervallo compreso tra 9 e 64.
Chiave binaria costituita da 32 byte di dati di chiave binaria. Il valore a cui punta il parametro pdwKeyLength deve essere 32 per la chiave binaria.

La chiave di sicurezza secondaria è persistente se il valore a cui punta il parametro pbPersistent è TRUE. Se persistente, la chiave di sicurezza secondaria viene usata immediatamente se la rete ospitata è già stata avviata e riutilizzata anche ogni volta che la rete ospitata viene avviata in futuro.

Se la chiave di sicurezza secondaria non viene specificata come persistente, verrà usata immediatamente se la rete ospitata è già stata avviata o solo per la successiva avvio della rete ospitata. Dopo l'arresto della rete ospitata, questa chiave di sicurezza secondaria non verrà mai più usata e verrà rimossa dal sistema.

Se non è attualmente configurata alcuna chiave di sicurezza secondaria, il valore restituito a cui punta il parametro pdwKeyLength sarà zero e il valore restituito nel parametro ppucKeyData sarà NULL. In tal caso, il valore restituito nei parametri pbIsPassPhrase e pbPersistent sarà senza significato.

Se la funzione WlanHostedNetworkQuerySecondaryKey ha esito positivo, la memoria utilizzata per il buffer nel parametro ppucKeyData restituito deve essere liberata dopo l'uso chiamando la funzione WlanFreeMemory .

Qualsiasi utente può chiamare la funzione WlanHostedNetworkQuerySecondaryKey per eseguire una query sulla chiave di sicurezza secondaria usata nella rete ospitata. Tuttavia, la possibilità di abilitare la rete ospitata wireless può essere limitata da criteri di gruppo in un dominio.

In Windows 7 e versioni successive il sistema operativo installa un dispositivo virtuale se nel computer è presente una scheda wireless con supporto per la rete ospitata. Questo dispositivo virtuale viene in genere visualizzato nella "cartella Connessioni di rete" come "Connessione di rete wireless 2" con un nome di dispositivo "Scheda Miniport WiFi virtuale Microsoft" se il computer ha una singola scheda di rete wireless. Questo dispositivo virtuale viene utilizzato esclusivamente per l'esecuzione di connessioni softAP (Software Access Point) e non è presente nell'elenco restituito dalla funzione WlanEnumInterfaces . La durata di questo dispositivo virtuale è associata alla scheda wireless fisica. Se la scheda wireless fisica è disabilitata, questo dispositivo virtuale verrà rimosso anche. Questa funzionalità è disponibile anche in Windows Server 2008 R2 con il servizio LAN wireless installato.

Requisiti


Client minimo supportato	Windows 7 [solo app desktop]
Server minimo supportato	Windows Server 2008 R2 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wlanapi.h (include Wlanapi.h)
Libreria	Wlanapi.lib
DLL	Wlanapi.dll