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:

[out, optional] pdwGrantedAccess

Maschera di accesso del profilo all-utente.

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.

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

Vedi anche

WLAN_PROFILE_INFO

WLAN_PROFILE_INFO_LIST

WLAN_SECURABLE_OBJECT

WLAN_profile Schema

WlanDeleteProfile

WlanEnumInterfaces

WlanFreeMemory

WlanGetProfileCustomUserData

WlanGetProfileList

WlanOpenHandle

WlanRenameProfile

WlanSaveTemporaryProfile

WlanSetProfile

WlanSetProfileCustomUserData

WlanSetProfileEapUserData

WlanSetProfileEapXmlUserData

WlanSetProfileList

WlanSetProfilePosition