Функция WlanSetProfile (wlanapi.h)
Функция 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. Профили отдельных пользователей не поддерживаются.
[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.
Если функция завершается сбоем, возвращаемое значение может быть одним из следующих кодов возврата.
| Код возврата | Описание |
|---|---|
|
Вызывающий объект не имеет достаточных разрешений для настройки профиля.
При вызове с параметром 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. |
|
strProfileXml указывает уже существующую сеть. Как правило, это возвращаемое значение используется, если параметр bOverwrite имеет значение FALSE; Однако если параметр bOverwrite имеет значение TRUE , а dwFlags указывает тип профиля, отличный от типа, используемого существующим профилем, то существующий профиль не будет перезаписан и ERROR_ALREADY_EXISTS будет возвращен. |
|
Недопустимый профиль, указанный в strProfileXml . Если это значение возвращается, pdwReasonCode указывает причину недопустимости профиля. |
|
Произошло одно из следующих условий:
<ConfigBlob>00</ConfigBlob> в профиле.
|
|
Интерфейс не поддерживает одну или несколько возможностей, указанных в профиле. Например, если профиль указывает использование WPA2, если сетевой адаптер поддерживает только WPA, возвращается этот код ошибки. Кроме того, если профиль указывает использование режима FIPS, если сетевой адаптер не поддерживает режим FIPS, возвращается этот код ошибки. |
|
Различные коды ошибок. |
Комментарии
Функцию WlanSetProfile можно использовать для добавления нового профиля беспроводной локальной сети или замены существующего профиля беспроводной локальной сети.
Новый профиль добавляется в начало списка после профилей групповой политики. Позиция профиля в списке не изменяется, если существующий профиль перезаписан. 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 для преобразования дескриптора в строку.
Для каждого профиля беспроводной локальной сети, используемого собственной службой автонастройки 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) |
См. также раздел
ConvertSecurityDescriptorToStringSecurityDescriptor
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по