Funzione WlanSetProfile (wlanapi.h)
La funzione WlanSetProfile imposta il contenuto di un profilo specifico.
Sintassi
DWORD WlanSetProfile(
[in] HANDLE hClientHandle,
[in] const GUID *pInterfaceGuid,
[in] DWORD dwFlags,
[in] LPCWSTR strProfileXml,
[in, optional] LPCWSTR strAllUserProfileSecurity,
[in] BOOL bOverwrite,
[in] PVOID pReserved,
[out] DWORD *pdwReasonCode
);
Parametri
[in] hClientHandle
Handle di sessione del client ottenuto da una chiamata precedente alla funzione WlanOpenHandle .
[in] pInterfaceGuid
GUID dell'interfaccia.
[in] dwFlags
Flag da impostare sul profilo.
Windows XP con SP3 e API LAN wireless per Windows XP con SP2: dwFlags deve essere 0. I profili per utente non sono supportati.
[in] strProfileXml
Contiene la rappresentazione XML del profilo. L'elemento WLANProfile è l'elemento del profilo radice. Per visualizzare i profili di esempio, vedere Esempi di profilo wireless. Non esiste una lunghezza massima predefinita.
Windows XP con SP3 e API LAN wireless per Windows XP con SP2: Il profilo fornito deve soddisfare i criteri di compatibilità descritti in Compatibilità del profilo wireless.
[in, optional] strAllUserProfileSecurity
Imposta la stringa del descrittore di sicurezza nel profilo all-user. Per altre informazioni sulle autorizzazioni del profilo, vedere la sezione Osservazioni.
Se dwFlags è impostato su WLAN_PROFILE_USER, questo parametro viene ignorato.
Se questo parametro è impostato su NULL per un nuovo profilo utente all-user, viene usato il descrittore di sicurezza associato all'oggetto wlan_secure_add_new_all_user_profiles. Se il descrittore di sicurezza non è stato modificato da una chiamata WlanSetSecuritySettings , tutti gli utenti hanno le autorizzazioni predefinite per un nuovo profilo utente. Chiamare WlanGetSecuritySettings per ottenere le autorizzazioni predefinite associate all'oggetto wlan_secure_add_new_all_user_profiles.
Se questo parametro è impostato su NULL per un profilo all-user esistente, le autorizzazioni del profilo non vengono modificate.
Se questo parametro non è NULL per un profilo utente all-user, la stringa del descrittore di sicurezza associata al profilo viene creata o modificata dopo la creazione e l'analisi dell'oggetto descrittore di sicurezza come stringa.
Windows XP con SP3 e API LAN wireless per Windows XP con SP2: Questo parametro deve essere NULL.
[in] bOverwrite
Specifica se questo profilo sovrascrive un profilo esistente. Se questo parametro è FALSE e il profilo esiste già, il profilo esistente non verrà sovrascritto e verrà restituito un errore.
[in] pReserved
Riservato per utilizzi futuri. Deve essere impostato su NULL.
[out] pdwReasonCode
Valore WLAN_REASON_CODE che indica perché il profilo non è valido.
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 |
|---|---|
|
Il chiamante non dispone di autorizzazioni sufficienti per impostare il profilo.
Quando viene chiamato con dwFlags impostato su 0, ovvero quando si imposta un profilo all-user - WlanSetProfile recupera l'elenco di controllo di accesso discrezionale archiviato con l'oggetto wlan_secure_add_new_all_user_profiles . Quando viene chiamato con dwFlags impostato su WLAN_PROFILE_USER , ovvero quando si imposta un profilo per utente - WlanSetProfile recupera l'elenco di controllo di accesso discrezionale archiviato con l'oggetto wlan_secure_add_new_per_user_profiles . In entrambi i casi, se l'elenco dati non contiene una voce di controllo di accesso (ACE) che concede l'autorizzazione WLAN_WRITE_ACCESS al token di accesso del thread chiamante, WlanSetProfile restituisce ERROR_ACCESS_DENIED. |
|
strProfileXml specifica una rete già esistente. In genere, questo valore restituito viene usato quando bOverwrite è FALSE; tuttavia, se bOverwrite è TRUE e dwFlags specifica un tipo di profilo diverso rispetto a quello usato dal profilo esistente, il profilo esistente non verrà sovrascritto e ERROR_ALREADY_EXISTS verrà restituito. |
|
Il profilo specificato da strProfileXml non è valido. Se questo valore viene restituito, pdwReasonCode specifica il motivo per cui il profilo non è valido. |
|
Si è verificata una delle seguenti condizioni:
<ConfigBlob>00</ConfigBlob> nel profilo.
|
|
L'interfaccia non supporta una o più funzionalità specificate nel profilo. Ad esempio, se un profilo specifica l'uso di WPA2 quando la scheda di interfaccia di rete supporta solo WPA, viene restituito questo codice di errore. Inoltre, se un profilo specifica l'uso della modalità FIPS quando la scheda di interfaccia di rete non supporta la modalità FIPS, viene restituito questo codice di errore. |
|
Vari codici di errore. |
Commenti
La funzione WlanSetProfile può essere usata per aggiungere un nuovo profilo LAN wireless o sostituire un profilo LAN wireless esistente.
Un nuovo profilo viene aggiunto nella parte superiore dell'elenco dopo i profili dei criteri di gruppo. La posizione di un profilo nell'elenco non viene modificata se un profilo esistente viene sovrascritto. Windows XP con SP3 e API LAN wireless per Windows XP con SP2:
I profili ad hoc vengono visualizzati dopo i profili di infrastruttura nell'elenco dei profili. Se si crea un nuovo profilo ad hoc, viene inserito nella parte superiore dell'elenco ad hoc, dopo i criteri di gruppo e i profili di infrastruttura.
I profili guest 802.1X, i profili del servizio di provisioning wireless (WPS) e i profili con Wi-Fi Access-None protetta (WPA-None) non sono supportati. Ciò significa che tale profilo non può essere creato, eliminato, enumerato o accessibile usando funzioni Native Wifi. Qualsiasi profilo già incluso nell'elenco dei profili preferito rimarrà nell'elenco e la sua posizione nell'elenco rispetto ad altri profili viene fissa a meno che la posizione degli altri profili non cambi.
È possibile chiamare WlanSetProfile in un profilo contenente una chiave di testo non crittografato, ovvero un profilo con l'elemento protetto presente e impostato su FALSE. Prima che il profilo venga salvato nell'archivio profili, il materiale della chiave viene crittografato automaticamente. Quando il profilo viene successivamente recuperato dall'archivio profili chiamando WlanGetProfile, viene restituito il materiale della chiave crittografato. Windows XP con SP3 e API LAN wireless per Windows XP con SP2: Il materiale della chiave non viene mai crittografato.
Tutti i profili utente hanno tre autorizzazioni associate: lettura, scrittura ed esecuzione. Se un utente ha accesso in lettura, l'utente può visualizzare le autorizzazioni del profilo. Se un utente ha accesso eseguito, l'utente ha accesso in lettura e l'utente può connettersi e disconnettersi da una rete usando il profilo. Se un utente ha accesso in scrittura, l'utente ha accesso e l'utente può anche modificare ed eliminare le autorizzazioni associate a un profilo.
Di seguito viene descritta la procedura per la creazione di un oggetto descrittore di sicurezza e l'analisi come stringa.
- Chiamare InitializeSecurityDescriptor per creare un descrittore di sicurezza in memoria.
- Chiamare SetSecurityDescriptorOwner.
- Chiamare InitializeAcl per creare un elenco di controllo di accesso discrezionale (DACL) in memoria.
- Chiamare AddAccessAllowedAce o AddAccessDeniedAce per aggiungere voci di controllo di accesso (ACEs) all'elenco di controllo di accesso. Impostare il parametro AccessMask su uno dei seguenti elementi:
- WLAN_READ_ACCESS
- WLAN_EXECUTE_ACCESS
- WLAN_WRITE_ACCESS
- Chiamare SetSecurityDescriptorDacl per aggiungere l'elenco dati al descrittore di sicurezza.
- Chiamare ConvertSecurityDescriptorToStringSecurityDescriptor per convertire il descrittore in stringa.
Per ogni profilo LAN wireless usato dal servizio Native Wifi AutoConfig, Windows mantiene il concetto di dati utente personalizzati. Questi dati utente personalizzati non sono inizialmente esistenti, ma possono essere impostati chiamando la funzione WlanSetProfileCustomUserData . I dati utente personalizzati vengono reimpostati in qualsiasi momento in cui il profilo viene modificato chiamando la funzione WlanSetProfile . Dopo aver impostato i dati utente personalizzati, questi dati possono essere accessibili usando la funzione WlanGetProfileCustomUserData .
Tutte le funzioni LAN wireless richiedono un GUID di interfaccia per l'interfaccia wireless durante l'esecuzione delle operazioni del profilo. Quando un'interfaccia wireless viene rimossa, lo stato viene cancellato dal servizio LAN wireless (WLANSVC) e non sono possibili operazioni di profilo.
La funzione WlanSetProfile può non riuscire con ERROR_INVALID_PARAMETER se l'interfaccia wireless specificata nel parametro pInterfaceGuid è stata rimossa dal sistema (una scheda wireless USB che è stata rimossa, ad esempio).
Il comando netsh wlan add profile offre funzionalità simili nella riga di comando. Per altre informazioni, vedere Comandi netsh per la rete locale wireless (wlan).
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows Vista, Windows XP con SP3 [solo app desktop] |
| Server minimo supportato | Windows Server 2008 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | wlanapi.h (include Wlanapi.h) |
| Libreria | Wlanapi.lib |
| DLL | Wlanapi.dll |
| Componente ridistribuibile | API LAN wireless per Windows XP con SP2 |
Vedi anche
ConvertSecurityDescriptorToStringSecurityDescriptor