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

Статья
03/15/2023

Функция WlanHostedNetworkSetSecondaryKey настраивает вторичный ключ безопасности, который будет использоваться беспроводной размещенной сетью.

Синтаксис

DWORD WlanHostedNetworkSetSecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [in]            DWORD                       dwKeyLength,
  [in]            PUCHAR                      pucKeyData,
  [in]            BOOL                        bIsPassPhrase,
  [in]            BOOL                        bPersistent,
  [out, optional] PWLAN_HOSTED_NETWORK_REASON pFailReason,
                  PVOID                       pvReserved
);

Параметры

[in] hClientHandle

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

[in] dwKeyLength

Количество допустимых байтов данных в массиве данных ключей, на который указывает параметр pucKeyData . Эта длина ключа должна включать завершающееся "\0", если ключ является парольной фразой.

[in] pucKeyData

Указатель на буфер, содержащий данные ключа. Количество допустимых байтов данных в буфере должно быть не менее значения, указанного в параметре dwKeyLength .

[in] bIsPassPhrase

Логическое значение, указывающее, имеет ли массив данных ключей, на который указывает параметр pucKeyData , в формате парольной фразы.

Если этот параметр имеет значение TRUE, массив данных ключей имеет формат парольной фразы. Если этот параметр имеет значение FALSE, массив данных ключей не имеет формат парольной фразы.

[in] bPersistent

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

Если этот параметр имеет значение TRUE, то массив данных ключей будет сохранен и повторно использован позже. Если этот параметр имеет значение FALSE, массив данных ключей будет использоваться для одного сеанса (текущего или следующего сеанса, если размещенная сеть не запущена).

[out, optional] pFailReason

Необязательный указатель на значение, которое получает причину сбоя, если вызов функции WlanHostedNetworkSetSecondaryKey завершается сбоем. Возможные значения для причины сбоя относятся к типу перечисления WLAN_HOSTED_NETWORK_REASON , определенному в файле заголовка Wlanapi.h .

pvReserved

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

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

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

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

Код возврата	Описание
ERROR_INVALID_HANDLE	Недопустимый дескриптор. Эта ошибка возвращается, если дескриптор, указанный в параметре hClientHandle , не найден в таблице дескрипторов.
ERROR_INVALID_PARAMETER	Неправильный параметр. Эта ошибка возвращается при возникновении любого из следующих условий: hClientHandle имеет значение NULL. pucKeyData имеет значение NULL. pucKeyData не указывает на правильный допустимый ключ. pvReserved не равно NULL.
ERROR_INVALID_STATE	Ресурс находится в неправильном состоянии для выполнения запрошенной операции. Это может произойти, если беспроводная размещенная сеть находилась в процессе завершения работы.
ERROR_SERVICE_NOT_ACTIVE	Служба не запущена. Эта ошибка возвращается, если служба автонастройки WLAN не запущена.
Другое	Различные коды RPC и другие коды ошибок. Используйте FormatMessage , чтобы получить строку сообщения для возвращенной ошибки.

Функция WlanHostedNetworkSetSecondaryKey — это расширение собственных беспроводных API, добавленных для поддержки беспроводной сети в Windows 7 и Windows Server 2008 R2 с установленной службой беспроводной локальной сети.

Клиентское приложение вызывает функцию WlanHostedNetworkSetSecondaryKey для настройки вторичного ключа безопасности, который будет использоваться беспроводной размещенной сетью. Любое изменение размещенной сети, вызванное этой функцией, не будет автоматически отменено, если вызывающее приложение закрывает свой вызывающий дескриптор (путем вызова WlanCloseHandle с параметром hClientHandle ) или если процесс завершается.

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

Вторичный ключ безопасности, переданный в буфер, на который указывает параметр pucKeyData , используется с проверкой подлинности WPA2-Personal и должен иметь один из следующих форматов:

Парольная фраза ключа, состоящая из массива символов ASCII от 8 до 63 символов. Параметр dwKeyLength должен содержать завершающий "\0" в парольной фразе. Значение параметра dwKeyLength должно находиться в диапазоне от 9 до 64.
Двоичный ключ, состоящий из 32 байт данных двоичного ключа. Параметр dwKeyLength должен иметь значение 32 для двоичного ключа.

Чтобы настроить допустимый вторичный ключ безопасности, параметр dwKeyLength должен находиться в правильном диапазоне, а параметр pucKeyData должен указывать на допустимый буфер памяти, содержащий указанные байты данных. Чтобы удалить настроенный вторичный ключ безопасности из системы, приложение должно вызвать функцию WlanHostedNetworkSetSecondaryKey с нулевым значением в параметре dwKeyLength и null в параметре pucKeyData .

Функция WlanHostedNetworkSetSecondaryKey вернет ERROR_INVALID_PARAMETER , если параметр pucKeyData имеет значение NULL, но параметр dwKeyLength не равен нулю. Функция WlanHostedNetworkSetSecondaryKey также вернет ERROR_INVALID_PARAMETER , если параметр dwKeyLength равен нулю, но параметр pucKeyData не равен NULL.

Вторичный ключ безопасности обычно устанавливается перед запуском беспроводной размещенной сети. Затем он будет использоваться при следующем запуске размещенной сети.

Вторичный ключ безопасности также можно задать после запуска размещенной сети. В этом случае вторичный ключ безопасности будет использоваться немедленно. Все клиенты, использующие предыдущий вторичный ключ безопасности, останутся подключенными, но они не смогут повторно подключиться, если по какой-либо причине они будут отключены или если беспроводная размещенная сеть перезапущена.

Вторичный ключ безопасности можно указать как постоянный, если для параметра bPersistent задано значение TRUE. Если указано как постоянный, вторичный ключ безопасности будет использоваться немедленно, если размещенная сеть уже запущена, а также повторно использоваться при запуске размещенной сети в будущем.

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

Любой пользователь может вызвать эту функцию, чтобы настроить вторичный ключ безопасности для использования в размещенной сети. Однако возможность включения беспроводной размещенной сети может быть ограничена групповой политикой в домене.

В Windows 7 и более поздних версиях операционная система устанавливает виртуальное устройство, если на компьютере присутствует беспроводной адаптер с поддержкой размещенной сети. Это виртуальное устройство обычно отображается в папке "Сетевые подключения" как "Беспроводное сетевое подключение 2" с именем устройства "Microsoft Virtual WiFi Miniport adapter", если компьютер имеет один беспроводной сетевой адаптер. Это виртуальное устройство используется исключительно для выполнения подключений к точкам доступа программного обеспечения (SoftAP) и отсутствует в списке, возвращаемом функцией WlanEnumInterfaces . Время существования этого виртуального устройства привязано к физическому беспроводному адаптеру. Если физический беспроводной адаптер отключен, это виртуальное устройство также будет удалено. Эта функция также доступна в Windows Server 2008 R2 с установленной службой беспроводной локальной сети.

Требования


Минимальная версия клиента	Windows 7 [только классические приложения]
Минимальная версия сервера	Windows Server 2008 R2 [только классические приложения]
Целевая платформа	Windows
Header	wlanapi.h (включая Wlanapi.h)
Библиотека	Wlanapi.lib
DLL	Wlanapi.dll