Funzione WlanGetProfile (wlanapi.h)
La funzione WlanGetProfile recupera tutte le informazioni su un profilo wireless specificato.
Sintassi
DWORD WlanGetProfile(
[in] HANDLE hClientHandle,
[in] const GUID *pInterfaceGuid,
[in] LPCWSTR strProfileName,
[in] PVOID pReserved,
[out] LPWSTR *pstrProfileXml,
[in, out, optional] DWORD *pdwFlags,
[out, optional] DWORD *pdwGrantedAccess
);
Parametri
[in] hClientHandle
Handle di sessione del client, ottenuto da una chiamata precedente alla funzione WlanOpenHandle .
[in] pInterfaceGuid
GUID dell'interfaccia wireless.
È possibile recuperare un elenco dei GUID per le interfacce wireless nel computer locale usando la funzione WlanEnumInterfaces .
[in] strProfileName
Nome del profilo. I nomi dei profili fanno distinzione tra maiuscole e minuscole. Questa stringa deve essere con terminazione NULL. La lunghezza massima del nome del profilo è di 255 caratteri. Ciò significa che la lunghezza massima di questa stringa, incluso il carattere di terminazione NULL, è di 256 caratteri.
Windows XP con SP3 e API LAN wireless per Windows XP con SP2: Il nome del profilo viene derivato automaticamente dall'SSID della rete. Per i profili di rete dell'infrastruttura, il nome del profilo è il SSID della rete. Per i profili di rete ad hoc, il nome del profilo è l'SSID della rete ad hoc seguita da -adhoc.
[in] pReserved
Riservato per utilizzi futuri. Deve essere impostato su NULL.
[out] pstrProfileXml
Stringa che rappresenta la rappresentazione XML del profilo sottoposto a query. Non esiste una lunghezza massima predefinita della stringa.
[in, out, optional] pdwFlags
In input, un puntatore alla posizione dell'indirizzo usata per fornire informazioni aggiuntive sulla richiesta. Se questo parametro è NULL nell'input, non verranno restituite informazioni sui flag del profilo. Nell'output, un puntatore alla posizione dell'indirizzo usata per ricevere i flag del profilo.
Windows XP con SP3 e API LAN wireless per Windows XP con SP2: I profili per utente non sono supportati. Impostare questo parametro su NULL.
Il parametro pdwFlags può puntare a un percorso di indirizzo contenente i valori seguenti:
| Valore | Significato |
|---|---|
|
In input, questo flag indica che il chiamante vuole recuperare la chiave di testo normale da un profilo wireless. Se il thread chiamante dispone delle autorizzazioni necessarie, la funzione WlanGetProfile restituisce la chiave di testo normale nell'elemento keyMaterial del profilo restituito nel buffer a cui punta il parametro pstrProfileXml .
Affinché la chiamata WlanGetProfile restituisca la chiave di testo normale, le autorizzazioni wlan_secure_get_plaintext_key dal tipo enumerato WLAN_SECURABLE_OBJECT devono essere impostate sul thread chiamante. L'elenco DACL deve contenere anche un ace che concede WLAN_READ_ACCESS l'autorizzazione al token di accesso del thread chiamante. Per impostazione predefinita, le autorizzazioni per il recupero della chiave di testo normale sono consentite solo ai membri del gruppo Administrators in un computer locale. Se il thread chiamante non dispone delle autorizzazioni necessarie, la funzione WlanGetProfile restituisce la chiave crittografata nell'elemento keyMaterial del profilo restituito nel buffer a cui punta il parametro pstrProfileXml . Non viene restituito alcun errore se il thread chiamante non dispone delle autorizzazioni necessarie. Windows 7: Questo flag passato all'input è un'estensione per le API wireless native aggiunte in Windows 7 e versioni successive. Il parametro pdwFlags è un parametro __inout_opt in Windows 7 e versioni successive. |
|
In caso di esito positivo della chiamata WlanGetProfile , questo flag indica che questo profilo è stato creato da Criteri di gruppo. Un profilo di Criteri di gruppo è di sola lettura. Né il contenuto né l'ordine di preferenza del profilo possono essere modificati. |
|
Quando la chiamata WlanGetProfile ha esito positivo, questo flag indica che il profilo è un profilo utente per l'utente specifico nel cui contesto risiede il thread chiamante. Se non è impostato, questo profilo è un profilo all-user. |
[out, optional] pdwGrantedAccess
Maschera di accesso del profilo all-utente.
| Valore | Significato |
|---|---|
|
L'utente può visualizzare il contenuto del profilo. |
|
L'utente ha accesso in lettura e l'utente può anche connettersi e disconnettersi da una rete usando il profilo. Se un utente ha WLAN_EXECUTE_ACCESS, l'utente ha anche WLAN_READ_ACCESS. |
|
L'utente ha eseguito l'accesso e l'utente può anche modificare il contenuto del profilo o eliminare il profilo. Se un utente ha WLAN_WRITE_ACCESS, l'utente ha anche WLAN_EXECUTE_ACCESS e WLAN_READ_ACCESS. |
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 |
|---|---|
|
Il chiamante non dispone di autorizzazioni sufficienti. Questo errore viene restituito se il parametro pstrProfileXml specifica un profilo all-utente, ma il chiamante non ha accesso in lettura al profilo. |
|
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 verifica una delle condizioni seguenti:
|
|
Non è disponibile spazio di archiviazione sufficiente per elaborare questo comando. Questo errore viene restituito se il sistema non è riuscito ad allocare memoria per il profilo. |
|
Il profilo specificato da strProfileName non è stato trovato. |
|
Vari codici di errore RPC e altri. Usare FormatMessage per ottenere la stringa del messaggio per l'errore restituito. |
Commenti
Se la funzione WlanGetProfile ha esito positivo, il profilo wireless viene restituito nel buffer a cui punta il parametro pstrProfileXml . Il buffer contiene una stringa che rappresenta la rappresentazione XML del profilo sottoposto a query. Per una descrizione della rappresentazione XML del profilo wireless, vedere WLAN_profile Schema.
Il chiamante è responsabile della chiamata della funzione WlanFreeMemory per liberare la memoria allocata per il puntatore del buffer al parametro pstrProfileXml quando il buffer non è più necessario.
Se pstrProfileXml specifica un profilo all-user, il chiamante WlanGetProfile deve avere accesso in lettura al profilo. In caso contrario, la chiamata WlanGetProfile avrà esito negativo con un valore restituito di ERROR_ACCESS_DENIED. Le autorizzazioni per un profilo utente vengono stabilite quando il profilo viene creato o salvato usando WlanSetProfile o WlanSaveTemporaryProfile.
Windows 7:
L'elemento keyMaterial restituito nello schema del profilo a cui punta pstrProfileXml può essere richiesto come testo non crittografato se la funzione WlanGetProfile viene chiamata con il flag WLAN_PROFILE_GET_PLAINTEXT_KEY impostato nel valore a cui punta il parametro pdwFlags all'input.
Per una chiave WEP, è possibile usare sia 5 caratteri ASCII che 10 caratteri esadecimali per impostare la chiave di testo non crittografato quando il profilo viene creato o aggiornato. Tuttavia, un profilo WEP verrà salvato con 10 caratteri esadecimali nella chiave indipendentemente dall'input originale usato per creare il profilo. Quindi, nel profilo restituito dalla funzione WlanGetProfile , la chiave WEP in testo non crittografato viene sempre restituita come 10 caratteri esadecimali.
Affinché la chiamata WlanGetProfile restituisca la chiave di testo normale, le autorizzazioni wlan_secure_get_plaintext_key dal tipo enumerato WLAN_SECURABLE_OBJECT devono essere impostate sul thread chiamante. L'elenco DACL deve contenere anche un ace che concede WLAN_READ_ACCESS l'autorizzazione al token di accesso del thread chiamante. Per impostazione predefinita, le autorizzazioni per il recupero della chiave di testo normale sono consentite solo ai membri del gruppo Administrators in un computer locale.
Se il thread chiamante non dispone delle autorizzazioni necessarie, la funzione WlanGetProfile restituisce la chiave crittografata nell'elemento keyMaterial del profilo restituito nel buffer a cui fa riferimento il parametro pstrProfileXml . Non viene restituito alcun errore se il thread chiamante non dispone delle autorizzazioni necessarie.
Per impostazione predefinita, l'elemento keyMaterial restituito nel profilo a cui fa riferimento pstrProfileXml viene crittografato. Se il processo viene eseguito nel contesto dell'account LocalSystem nello stesso computer, è possibile annullare la crittografia del materiale della chiave chiamando la funzione CryptUnprotectData .
Windows Server 2008 e Windows Vista: L'elemento keyMaterial restituito nello schema del profilo a cui fa riferimento pstrProfileXml viene sempre crittografato. Se il processo viene eseguito nel contesto dell'account LocalSystem, è possibile annullare la crittografia del materiale della chiave chiamando la funzione CryptUnprotectData .
Windows XP con SP3 e API LAN wireless per Windows XP con SP2: Il materiale della chiave non viene mai crittografato.
Esempio
L'esempio seguente enumera le interfacce LAN wireless nel computer locale, recupera informazioni per un profilo wireless specifico in ogni interfaccia LAN wireless e stampa i valori recuperati. Viene stampata anche la stringa che rappresenta la rappresentazione XML del profilo sottoposto a query.
#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <wlanapi.h>
#include <objbase.h>
#include <wtypes.h>
#include <stdio.h>
#include <stdlib.h>
// Need to link with Wlanapi.lib and Ole32.lib
#pragma comment(lib, "wlanapi.lib")
#pragma comment(lib, "ole32.lib")
int _cdecl wmain(int argc, WCHAR **argv)
{
// Declare and initialize variables.
HANDLE hClient = NULL;
DWORD dwMaxClient = 2; //
DWORD dwCurVersion = 0;
DWORD dwResult = 0;
DWORD dwRetVal = 0;
int iRet = 0;
WCHAR GuidString[39] = {0};
unsigned int i;
/* variables used for WlanEnumInterfaces */
PWLAN_INTERFACE_INFO_LIST pIfList = NULL;
PWLAN_INTERFACE_INFO pIfInfo = NULL;
LPCWSTR pProfileName = NULL;
LPWSTR pProfileXml = NULL;
DWORD dwFlags = 0;
DWORD dwGrantedAccess = 0;
// Validate the parameters
if (argc < 2) {
wprintf(L"usage: %s <profile>\n", argv[0]);
wprintf(L" Gets a wireless profile\n");
wprintf(L" Example\n");
wprintf(L" %s \"Default Wireless\"\n", argv[0]);
exit(1);
}
pProfileName = argv[1];
wprintf(L"Information for profile: %ws\n\n", pProfileName);
dwResult = WlanOpenHandle(dwMaxClient, NULL, &dwCurVersion, &hClient);
if (dwResult != ERROR_SUCCESS) {
wprintf(L"WlanOpenHandle failed with error: %u\n", dwResult);
return 1;
// You can use FormatMessage here to find out why the function failed
}
dwResult = WlanEnumInterfaces(hClient, NULL, &pIfList);
if (dwResult != ERROR_SUCCESS) {
wprintf(L"WlanEnumInterfaces failed with error: %u\n", dwResult);
return 1;
// You can use FormatMessage here to find out why the function failed
} else {
wprintf(L"WLAN_INTERFACE_INFO_LIST for this system\n");
wprintf(L"Num Entries: %lu\n", pIfList->dwNumberOfItems);
wprintf(L"Current Index: %lu\n\n", pIfList->dwIndex);
for (i = 0; i < (int) pIfList->dwNumberOfItems; i++) {
pIfInfo = (WLAN_INTERFACE_INFO *) &pIfList->InterfaceInfo[i];
wprintf(L" Interface Index[%u]:\t %lu\n", i, i);
iRet = StringFromGUID2(pIfInfo->InterfaceGuid, (LPOLESTR) &GuidString,
sizeof(GuidString)/sizeof(*GuidString));
// For c rather than C++ source code, the above line needs to be
// iRet = StringFromGUID2(&pIfInfo->InterfaceGuid, (LPOLESTR) &GuidString,
// sizeof(GuidString)/sizeof(*GuidString));
if (iRet == 0)
wprintf(L"StringFromGUID2 failed\n");
else {
wprintf(L" InterfaceGUID[%d]: %ws\n",i, GuidString);
}
wprintf(L" Interface Description[%d]: %ws", i,
pIfInfo->strInterfaceDescription);
wprintf(L"\n");
wprintf(L" Interface State[%d]:\t ", i);
switch (pIfInfo->isState) {
case wlan_interface_state_not_ready:
wprintf(L"Not ready\n");
break;
case wlan_interface_state_connected:
wprintf(L"Connected\n");
break;
case wlan_interface_state_ad_hoc_network_formed:
wprintf(L"First node in a ad hoc network\n");
break;
case wlan_interface_state_disconnecting:
wprintf(L"Disconnecting\n");
break;
case wlan_interface_state_disconnected:
wprintf(L"Not connected\n");
break;
case wlan_interface_state_associating:
wprintf(L"Attempting to associate with a network\n");
break;
case wlan_interface_state_discovering:
wprintf(L"Auto configuration is discovering settings for the network\n");
break;
case wlan_interface_state_authenticating:
wprintf(L"In process of authenticating\n");
break;
default:
wprintf(L"Unknown state %ld\n", pIfInfo->isState);
break;
}
wprintf(L"\n\n");
dwResult = WlanGetProfile(hClient,
&pIfInfo->InterfaceGuid,
pProfileName,
NULL,
&pProfileXml,
&dwFlags,
&dwGrantedAccess);
if (dwResult != ERROR_SUCCESS) {
wprintf(L"WlanGetProfile failed with error: %u\n",
dwResult);
// You can use FormatMessage to find out why the function failed
} else {
wprintf(L" Profile Name: %ws\n", pProfileName);
wprintf(L" Profile XML string:\n");
wprintf(L"%ws\n\n", pProfileXml);
wprintf(L" dwFlags:\t 0x%x", dwFlags);
// if (dwFlags & WLAN_PROFILE_GET_PLAINTEXT_KEY)
// wprintf(L" Get Plain Text Key");
if (dwFlags & WLAN_PROFILE_GROUP_POLICY)
wprintf(L" Group Policy");
if (dwFlags & WLAN_PROFILE_USER)
wprintf(L" Per User Profile");
wprintf(L"\n");
wprintf(L" dwGrantedAccess: 0x%x", dwGrantedAccess);
if (dwGrantedAccess & WLAN_READ_ACCESS)
wprintf(L" Read access");
if (dwGrantedAccess & WLAN_EXECUTE_ACCESS)
wprintf(L" Execute access");
if (dwGrantedAccess & WLAN_WRITE_ACCESS)
wprintf(L" Write access");
wprintf(L"\n");
wprintf(L"\n");
}
}
}
if (pProfileXml != NULL) {
WlanFreeMemory(pProfileXml);
pProfileXml = NULL;
}
if (pIfList != NULL) {
WlanFreeMemory(pIfList);
pIfList = NULL;
}
return dwRetVal;
}
Requisiti
| 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 |