Функция WlanGetProfile (wlanapi.h)
Функция WlanGetProfile извлекает все сведения об указанном профиле беспроводной сети.
Синтаксис
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
);
Параметры
[in] hClientHandle
Дескриптор сеанса клиента, полученный при предыдущем вызове функции WlanOpenHandle .
[in] pInterfaceGuid
GUID беспроводного интерфейса.
Список GUID для беспроводных интерфейсов на локальном компьютере можно получить с помощью функции WlanEnumInterfaces .
[in] strProfileName
Имя профиля. В именах профилей учитывается регистр. Эта строка должна заканчиваться значением NULL. Максимальная длина имени профиля составляет 255 символов. Это означает, что максимальная длина этой строки, включая признак конца NULL, составляет 256 символов.
Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2): Имя профиля автоматически выводится из SSID сети. Для профилей сети инфраструктуры именем профиля является SSID сети. Для нерегламентированных сетевых профилей именем профиля является SSID нерегламентированной сети, за которым следует -adhoc.
[in] pReserved
Зарезервировано для последующего использования. Для параметра должно быть задано значение NULL.
[out] pstrProfileXml
Строка, представляющее XML-представление запрашиваемого профиля. Предопределенная максимальная длина строки отсутствует.
[in, out, optional] pdwFlags
На входных данных — указатель на расположение адреса, используемое для предоставления дополнительных сведений о запросе. Если для входных данных этот параметр имеет значение NULL , то никакие сведения о флагах профиля не возвращаются. В выходных данных — указатель на расположение адреса, используемое для получения флагов профиля.
Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2): Профили отдельных пользователей не поддерживаются. Задайте для этого параметра значение NULL.
Параметр pdwFlags может указывать на адресное расположение, содержащее следующие значения:
| Значение | Значение |
|---|---|
|
При входе этот флаг указывает, что вызывающий объект хочет получить ключ в виде обычного текста из профиля беспроводной сети. Если вызывающий поток имеет необходимые разрешения, функция WlanGetProfile возвращает ключ обычного текста в элементе keyMaterial профиля, возвращаемого в буфере, на который указывает параметр pstrProfileXml .
Чтобы вызов WlanGetProfile возвращал ключ в виде обычного текста, в вызывающем потоке должны быть заданы разрешения wlan_secure_get_plaintext_key из перечисленного типа WLAN_SECURABLE_OBJECT . DaCL также должен содержать ACE, который предоставляет WLAN_READ_ACCESS разрешение маркеру доступа вызывающего потока. По умолчанию разрешения на получение ключа в виде обычного текста разрешены только членам группы "Администраторы" на локальном компьютере. Если вызывающий поток не имеет необходимых разрешений, функция WlanGetProfile возвращает зашифрованный ключ в элементе keyMaterial профиля, возвращаемого в буфере, на который указывает параметр pstrProfileXml . Ошибка не возвращается, если вызывающий поток не имеет необходимых разрешений. Windows 7: Этот флаг, передаваемый при входе, является расширением собственных беспроводных API, добавленных в Windows 7 и более поздних версий. Параметр pdwFlags является параметром __inout_opt в Windows 7 и более поздних версиях. |
|
В выходных данных при успешном вызове WlanGetProfile этот флаг указывает, что этот профиль был создан групповой политикой. Профиль групповой политики доступен только для чтения. Невозможно изменить ни содержимое, ни порядок предпочтений профиля. |
|
При успешном вызове WlanGetProfile этот флаг указывает, что профиль является профилем пользователя для конкретного пользователя, в контексте которого находится вызывающий поток. Если этот профиль не задан, это профиль для всех пользователей. |
[out, optional] pdwGrantedAccess
Маска доступа профиля для всех пользователей.
| Значение | Значение |
|---|---|
|
Пользователь может просматривать содержимое профиля. |
|
Пользователь имеет доступ на чтение, а также может подключаться к сети и отключаться от нее с помощью профиля. Если у пользователя есть WLAN_EXECUTE_ACCESS, у него также есть WLAN_READ_ACCESS. |
|
Пользователь имеет доступ к выполнению, и пользователь также может изменить содержимое профиля или удалить профиль. Если у пользователя есть WLAN_WRITE_ACCESS, у него также есть WLAN_EXECUTE_ACCESS и WLAN_READ_ACCESS. |
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение будет ERROR_SUCCESS.
Если функция завершается сбоем, возвращаемое значение может быть одним из следующих кодов возврата.
| Код возврата | Описание |
|---|---|
|
Вызывающий объект не имеет достаточных разрешений. Эта ошибка возвращается, если параметр pstrProfileXml указывает профиль всех пользователей, но вызывающий объект не имеет доступа на чтение в профиле. |
|
Недопустимый дескриптор. Эта ошибка возвращается, если дескриптор, указанный в параметре hClientHandle , не найден в таблице дескрипторов. |
|
Неправильный параметр. Эта ошибка возвращается при возникновении любого из следующих условий:
|
|
Недостаточно места для обработки этой команды. Эта ошибка возвращается, если системе не удалось выделить память для профиля. |
|
Профиль, указанный параметром strProfileName , не найден. |
|
Различные коды RPC и другие коды ошибок. Используйте FormatMessage , чтобы получить строку сообщения для возвращенной ошибки. |
Комментарии
Если функция WlanGetProfile завершается успешно, профиль беспроводной сети возвращается в буфере, на который указывает параметр pstrProfileXml . Буфер содержит строку, которая является XML-представлением запрашиваемого профиля. Описание XML-представления профиля беспроводной сети см. в разделе Схема WLAN_profile.
Вызывающий объект отвечает за вызов функции WlanFreeMemory для освобождения памяти, выделенной для указателя буфера с помощью параметра pstrProfileXml , когда буфер больше не нужен.
Если pstrProfileXml указывает профиль для всех пользователей, вызывающий объект WlanGetProfile должен иметь доступ на чтение профиля. В противном случае вызов WlanGetProfile завершится ошибкой с возвращаемым значением ERROR_ACCESS_DENIED. Разрешения для профиля для всех пользователей устанавливаются при создании или сохранении профиля с помощью WlanSetProfile или WlanSaveTemporaryProfile.
Windows 7:
Элемент keyMaterial , возвращаемый в схеме профиля, на который указывает pstrProfileXml , может быть запрошен в виде открытого текста, если функция WlanGetProfile вызывается с флагом WLAN_PROFILE_GET_PLAINTEXT_KEY , установленным в значении, на которое указывает параметр pdwFlags во входных данных.
Для ключа WEP при создании или обновлении профиля можно использовать 5 символов ASCII или 10 шестнадцатеричных символов. Однако профиль WEP будет сохранен с 10 шестнадцатеричными символами в ключе независимо от того, какие исходные входные данные использовались для создания профиля. Таким образом, в профиле, возвращаемом функцией WlanGetProfile , ключ WEP в виде открытого текста всегда возвращается в виде 10 шестнадцатеричных символов.
Чтобы вызов WlanGetProfile возвращал ключ в виде обычного текста, в вызывающем потоке должны быть заданы разрешения wlan_secure_get_plaintext_key из перечисленного типа WLAN_SECURABLE_OBJECT . DaCL также должен содержать ACE, который предоставляет WLAN_READ_ACCESS разрешение маркеру доступа вызывающего потока. По умолчанию разрешения на получение ключа в виде обычного текста разрешены только членам группы "Администраторы" на локальном компьютере.
Если вызывающий поток не имеет необходимых разрешений, функция WlanGetProfile возвращает зашифрованный ключ в элементе keyMaterial профиля, возвращаемого в буфере, на который указывает параметр pstrProfileXml . Ошибка не возвращается, если вызывающий поток не имеет необходимых разрешений.
По умолчанию элемент keyMaterial , возвращаемый в профиле, на который указывает pstrProfileXml , шифруется. Если процесс выполняется в контексте учетной записи LocalSystem на том же компьютере, можно отменить шифрование материала ключа, вызвав функцию CryptUnprotectData .
Windows Server 2008 и Windows Vista: Элемент keyMaterial , возвращаемый в схеме профиля, на которую указывает pstrProfileXml , всегда шифруется. Если процесс выполняется в контексте учетной записи LocalSystem, можно отменить шифрование материала ключа, вызвав функцию CryptUnprotectData .
Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2): Материал ключа никогда не шифруется.
Примеры
В следующем примере перечисляются интерфейсы беспроводной локальной сети на локальном компьютере, извлекаются сведения для определенного профиля беспроводной сети в каждом интерфейсе беспроводной локальной сети и выводится полученные значения. Также выводится строка, которая представляет собой XML-представление запрашиваемого профиля.
#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;
}
Требования
| Минимальная версия клиента | Windows Vista, Windows XP с пакетом обновления 3 (SP3) [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 [только классические приложения] |
| Целевая платформа | Windows |
| Header | wlanapi.h (включая Wlanapi.h) |
| Библиотека | Wlanapi.lib |
| DLL | Wlanapi.dll |
| Распространяемые компоненты | API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2) |