Funzione WlanHostedNetworkSetSecondaryKey (wlanapi.h)
La funzione WlanHostedNetworkSetSecondaryKey configura la chiave di sicurezza secondaria che verrà usata dalla rete ospitata wireless.
Sintassi
DWORD WlanHostedNetworkSetSecondaryKey(
[in] HANDLE hClientHandle,
[in] DWORD dwKeyLength,
[in] PUCHAR pucKeyData,
[in] BOOL bIsPassPhrase,
[in] BOOL bPersistent,
[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 .
[in] dwKeyLength
Numero di byte di dati validi nella matrice di dati chiave a cui punta il parametro pucKeyData . Questa lunghezza della chiave deve includere la terminazione '\0' se la chiave è una passphrase.
[in] pucKeyData
Puntatore a un buffer contenente i dati delle chiavi. Il numero di byte di dati validi nel buffer deve essere almeno il valore specificato nel parametro dwKeyLength .
[in] bIsPassPhrase
Valore booleano che indica se la matrice di dati chiave puntata dal parametro pucKeyData è 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.
[in] bPersistent
Valore booleano che indica se la matrice di dati chiave puntata dal parametro pucKeyData deve essere archiviata e riutilizzata in un secondo momento o per un solo utilizzo.
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 deve essere usata per una sessione (la sessione corrente o la sessione successiva se la rete ospitata non viene avviata).
[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 è ERROR_SUCCESS.
Se la funzione ha esito negativo, il valore restituito può essere uno dei codici restituiti seguenti.
| Codice restituito | Descrizione |
|---|---|
|
Un handle non è valido. Questo errore viene restituito se l'handle specificato nel parametro hClientHandle non è stato trovato nella tabella handle. |
|
Un parametro non è corretto. Questo errore viene restituito se si verificano una delle condizioni seguenti:
|
|
La risorsa non è nello stato corretto per eseguire l'operazione richiesta. Ciò può verificarsi se la rete ospitata wireless è stata nel processo di arresto. |
|
Il servizio non è stato avviato. Questo errore viene restituito se il servizio AutoConfig WLAN non è in esecuzione. |
|
Vari codici di errore RPC e altri codici di errore. Usare FormatMessage per ottenere la stringa di messaggio per l'errore restituito. |
Commenti
La funzione WlanHostedNetworkSetSecondaryKey è un'estensione per le 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 WlanHostedNetworkSetSecondaryKey per configurare la chiave di sicurezza secondaria che verrà usata dalla rete ospitata wireless. Qualsiasi modifica di rete ospitata causata da questa funzione non verrà annullata automaticamente se l'applicazione chiamante chiude il relativo handle chiamante (chiamando WlanCloseHandle con il parametro hClientHandle ) o se il processo termina.
Dopo l'avvio, la rete ospitata wireless consentirà ai peer wireless di associare questa chiave di sicurezza secondaria oltre alla chiave di sicurezza primaria. La chiave di sicurezza secondaria viene sempre specificata dall'utente in base alle esigenze, mentre la chiave di sicurezza primaria viene generata dal sistema operativo con maggiore forza di sicurezza.
La chiave di sicurezza secondaria passata nel buffer a cui fa riferimento il parametro pucKeyData viene usata con l'autenticazione WPA2-Personal e deve trovarsi in uno dei formati seguenti:
- Passphrase chiave costituita da una matrice di caratteri ASCII da 8 a 63 caratteri. Il parametro dwKeyLength deve includere la terminazione '\0' nella passphrase. Il valore del parametro dwKeyLength deve trovarsi nell'intervallo compreso tra 9 e 64.
- Chiave binaria costituita da 32 byte di dati di chiave binaria. Il parametro dwKeyLength deve essere 32 per la chiave binaria.
Per configurare una chiave di sicurezza secondaria valida, il parametro dwKeyLength deve trovarsi nell'intervallo corretto e il parametro pucKeyData deve puntare a un buffer di memoria valido contenente i byte specificati di dati. Per rimuovere la chiave di sicurezza secondaria attualmente configurata dal sistema, l'applicazione deve chiamare la funzione WlanHostedNetworkSetSecondaryKey con zero nel parametro dwKeyLength e NULL nel parametro pucKeyData .
La funzione WlanHostedNetworkSetSecondaryKey restituirà ERROR_INVALID_PARAMETER se il parametro pucKeyData è NULL, ma il parametro dwKeyLength non è zero. La funzione WlanHostedNetworkSetSecondaryKey restituirà anche ERROR_INVALID_PARAMETER se il parametro dwKeyLength è zero, ma il parametro pucKeyData non è NULL.
La chiave di sicurezza secondaria viene in genere impostata prima dell'avvio della rete ospitata wireless. Verrà quindi usato la prossima volta che viene avviata la rete ospitata.
Una chiave di sicurezza secondaria può essere impostata anche dopo l'avvio della rete ospitata. In questo caso, la chiave di sicurezza secondaria verrà usata immediatamente. Tutti i client che usano la chiave di sicurezza secondaria precedente rimarranno connessi, ma non saranno in grado di riconnettersi se vengono disconnessi per qualsiasi motivo o se la rete ospitata wireless viene riavviata.
La chiave di sicurezza secondaria può essere specificata come persistente se il parametro bPersistent è impostato su TRUE. Se specificato come persistente, la chiave di sicurezza secondaria verrà usata immediatamente se la rete ospitata è già avviata e viene riutilizzata anche ogni volta che viene avviata la rete ospitata in futuro.
Se la chiave di sicurezza secondaria non viene specificata come persistente, verrà usata immediatamente se la rete ospitata è già avviata o solo per la prossima volta che viene avviata la rete ospitata. Dopo l'arresto della rete ospitata, questa chiave di sicurezza secondaria non verrà mai usata di nuovo e verrà rimossa dal sistema.
Qualsiasi utente può chiamare questa funzione per configurare la chiave di sicurezza secondaria da usare nella rete ospitata. Tuttavia, la possibilità di abilitare la rete ospitata wireless può essere limitata dai criteri di gruppo in un dominio.
In Windows 7 e versioni successive il sistema operativo installa un dispositivo virtuale se una scheda wireless con supporto per la rete ospitata è presente nel computer. Questo dispositivo virtuale viene normalmente visualizzato nella "cartella Connessioni di rete" come "Connessione di rete wireless 2" con un nome dispositivo di "Scheda Miniport WiFi virtuale Microsoft" se il computer ha una singola scheda di rete wireless. Questo dispositivo virtuale viene usato esclusivamente per eseguire 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 l'adattatore wireless fisico è disabilitato, 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 |
Vedi anche
Informazioni sulla rete ospitata wireless
Uso della rete ospitata wireless e della condivisione connessione Internet
WlanHostedNetworkQueryProperty
WlanHostedNetworkQuerySecondaryKey