Функция WlanSetProfile (wlanapi.h)

Статья
03/15/2023

Функция WlanSetProfile задает содержимое определенного профиля.

Синтаксис

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
);

Параметры

[in] hClientHandle

Дескриптор сеанса клиента, полученный при предыдущем вызове функции WlanOpenHandle .

[in] pInterfaceGuid

Идентификатор GUID интерфейса.

[in] dwFlags

Флаги, устанавливаемые для профиля.

Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2): dwFlags должно иметь значение 0. Профили отдельных пользователей не поддерживаются.

Значение	Значение
0	Профиль является профилем всех пользователей.
WLAN_PROFILE_GROUP_POLICY 0x00000001	Профиль является профилем групповой политики.
WLAN_PROFILE_USER 0x00000002	Профиль является профилем для каждого пользователя.

[in] strProfileXml

Содержит XML-представление профиля. Элемент WLANProfile является корневым элементом профиля. Сведения о просмотре примеров профилей см. в разделе Примеры профилей беспроводной сети. Предопределенная максимальная длина строки отсутствует.

Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2): Предоставленный профиль должен соответствовать критериям совместимости, описанным в разделе Совместимость беспроводных профилей.

[in, optional] strAllUserProfileSecurity

Задает строку дескриптора безопасности для профиля всех пользователей. Дополнительные сведения о разрешениях профиля см. в разделе Примечания.

Если параметр dwFlags имеет значение WLAN_PROFILE_USER, этот параметр игнорируется.

Если этот параметр имеет значение NULL для нового профиля для всех пользователей, используется дескриптор безопасности, связанный с объектом wlan_secure_add_new_all_user_profiles. Если дескриптор безопасности не был изменен вызовом WlanSetSecuritySettings , все пользователи имеют разрешения по умолчанию для нового профиля для всех пользователей. Вызовите WlanGetSecuritySettings , чтобы получить разрешения по умолчанию, связанные с объектом wlan_secure_add_new_all_user_profiles.

Если этот параметр имеет значение NULL для существующего профиля для всех пользователей, разрешения профиля не изменяются.

Если этот параметр не равен NULL для профиля для всех пользователей, строка дескриптора безопасности, связанная с профилем, создается или изменяется после создания и анализа объекта дескриптора безопасности в виде строки.

Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2): Этот параметр должен иметь значение NULL.

[in] bOverwrite

Указывает, перезаписывает ли этот профиль существующий профиль. Если этот параметр имеет значение FALSE и профиль уже существует, существующий профиль не будет перезаписан и будет возвращена ошибка.

[in] pReserved

Зарезервировано для последующего использования. Для параметра должно быть задано значение NULL.

[out] pdwReasonCode

Значение WLAN_REASON_CODE , указывающее, почему профиль недопустим.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение будет ERROR_SUCCESS.

Если функция завершается сбоем, возвращаемое значение может быть одним из следующих кодов возврата.

Код возврата	Описание
ERROR_ACCESS_DENIED	Вызывающий объект не имеет достаточных разрешений для настройки профиля. При вызове с параметром dwFlags , равным 0, то есть при настройке профиля для всех пользователей, WlanSetProfile извлекает список управления доступом на уровне пользователей (DACL), хранящийся в объекте wlan_secure_add_new_all_user_profiles . При вызове с параметром dwFlags , для которого задано значение WLAN_PROFILE_USER , то есть при настройке профиля пользователя, WlanSetProfile извлекает список управления доступом на уровне пользователей (DACL), хранящийся в объекте wlan_secure_add_new_per_user_profiles . В любом случае, если DACL не содержит запись управления доступом (ACE), которая предоставляет WLAN_WRITE_ACCESS разрешение на маркер доступа вызывающего потока, WlanSetProfile возвращает ERROR_ACCESS_DENIED.
ERROR_ALREADY_EXISTS	strProfileXml указывает уже существующую сеть. Как правило, это возвращаемое значение используется, если параметр bOverwrite имеет значение FALSE; Однако если параметр bOverwrite имеет значение TRUE , а dwFlags указывает тип профиля, отличный от типа, используемого существующим профилем, то существующий профиль не будет перезаписан и ERROR_ALREADY_EXISTS будет возвращен.
ERROR_BAD_PROFILE	Недопустимый профиль, указанный в strProfileXml . Если это значение возвращается, pdwReasonCode указывает причину недопустимости профиля.
ERROR_INVALID_PARAMETER	Произошло одно из следующих условий: Значение hClientHandle равно NULL или недопустимо. pInterfaceGuid имеет значение NULL. pReserved не равно NULL. StrProfileXml имеет значение NULL. [ConfigBlob] (/windows/desktop/eaphost/eaphostconfigschema-configblob-eaphostconfig-element). Если профиль должен иметь пустой объект ConfigBlob, используйте `<ConfigBlob>00</ConfigBlob>` в профиле. pdwReasonCode имеет значение NULL. Параметру dwFlags не задано ни одно из указанных значений. Параметру dwFlags присвоено значение WLAN_PROFILE_GROUP_POLICY, а параметру bOverwrite — значение FALSE.
ERROR_NO_MATCH	Интерфейс не поддерживает одну или несколько возможностей, указанных в профиле. Например, если профиль указывает использование WPA2, если сетевой адаптер поддерживает только WPA, возвращается этот код ошибки. Кроме того, если профиль указывает использование режима FIPS, если сетевой адаптер не поддерживает режим FIPS, возвращается этот код ошибки.
RPC_STATUS	Различные коды ошибок.

Новый профиль добавляется в начало списка после профилей групповой политики. Позиция профиля в списке не изменяется, если существующий профиль перезаписан. Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2):

Нерегламентированные профили отображаются после профилей инфраструктуры в списке профилей. При создании нового нерегламентированного профиля он помещается в начало списка ad hoc после профилей групповой политики и инфраструктуры.

Гостевые профили 802.1X, профили службы беспроводной подготовки (WPS) и профили с проверкой подлинности Wi-Fi защищенных Access-None (WPA-None) не поддерживаются. Это означает, что такой профиль нельзя создать, удалить, перечислить или получить к ней доступ с помощью собственных функций Wi-Fi. Любой такой профиль, который уже находится в списке предпочтительных профилей, останется в списке, а его положение в списке относительно других профилей будет фиксировано, если положение других профилей не изменится.

Вы можете вызвать WlanSetProfile для профиля, содержащего ключ в виде открытого текста (то есть профиля с защищенным элементом, который имеет значение FALSE). Перед сохранением профиля в хранилище профилей материал ключа автоматически шифруется. При последующем извлечении профиля из хранилища профилей путем вызова WlanGetProfile возвращается зашифрованный материал ключа. Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2): Материал ключа никогда не шифруется.

Профили всех пользователей имеют три связанных разрешения: чтение, запись и выполнение. Если у пользователя есть доступ на чтение, он может просматривать разрешения профиля. Если у пользователя есть доступ на выполнение, у него есть доступ на чтение, и пользователь также может подключаться к сети и отключаться от нее с помощью профиля. Если у пользователя есть доступ на запись, у него есть доступ на выполнение, и пользователь также может изменять и удалять разрешения, связанные с профилем.

Ниже описана процедура создания объекта дескриптора безопасности и его анализа в виде строки.

Вызовите InitializeSecurityDescriptor , чтобы создать дескриптор безопасности в памяти.
Вызовите SetSecurityDescriptorOwner.
Вызовите Метод InitializeAcl , чтобы создать список управления доступом на уровне пользователей (DACL) в памяти.
Вызовите метод AddAccessAllowedAce или AddAccessDeniedAce , чтобы добавить записи управления доступом (ACE) в DACL. Задайте для параметра AccessMask одно из следующих значений.
- WLAN_READ_ACCESS
- WLAN_EXECUTE_ACCESS
- WLAN_WRITE_ACCESS
Вызовите Метод SetSecurityDescriptorDacl , чтобы добавить DACL в дескриптор безопасности.
Вызовите Метод ConvertSecurityDescriptorToStringSecurityDescriptor для преобразования дескриптора в строку.

Строка, возвращаемая ConvertSecurityDescriptorToStringSecurityDescriptor , затем может использоваться в качестве значения параметра strAllUserProfileSecurity при вызове WlanSetProfile.

Для каждого профиля беспроводной локальной сети, используемого собственной службой автонастройки Wi-Fi, Windows поддерживает концепцию пользовательских данных пользователя. Эти пользовательские данные изначально отсутствуют, но их можно задать, вызвав функцию WlanSetProfileCustomUserData . Пользовательские данные пользователя сбрасываются на пустые при изменении профиля путем вызова функции WlanSetProfile . После настройки пользовательских данных к этим данным можно получить доступ с помощью функции WlanGetProfileCustomUserData .

Для всех функций беспроводной локальной сети требуется guid интерфейса для беспроводного интерфейса при выполнении операций с профилем. При удалении беспроводного интерфейса его состояние удаляется из службы беспроводной локальной сети (WLANSVC) и операции с профилем невозможны.

Функция WlanSetProfile может завершиться сбоем с ERROR_INVALID_PARAMETER , если беспроводной интерфейс, указанный в параметре pInterfaceGuid , был удален из системы (например, беспроводной адаптер USB, который был удален).

Команда netsh wlan add profile предоставляет аналогичные функции в командной строке. Дополнительные сведения см. в разделе Команды Netsh для беспроводной локальной сети (wlan).

Требования

Требование	Значение
Минимальная версия клиента	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)