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

Статья
08/28/2023

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

Синтаксис

DWORD WlanHostedNetworkQuerySecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [out]           PDWORD                      pdwKeyLength,
  [out]           PUCHAR                      *ppucKeyData,
  [out]           PBOOL                       pbIsPassPhrase,
  [out]           PBOOL                       pbPersistent,
  [out, optional] PWLAN_HOSTED_NETWORK_REASON pFailReason,
                  PVOID                       pvReserved
);

Параметры

[in] hClientHandle

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

[out] pdwKeyLength

Указатель на значение, указывающее количество допустимых байтов данных в массиве ключевых данных, на который указывает параметр ppucKeyData , если вызов функции WlanHostedNetworkQuerySecondaryKey выполнен успешно.

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

[out] ppucKeyData

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

[out] pbIsPassPhrase

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

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

[out] pbPersistent

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

Если этот параметр имеет значение 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. pdwKeyLength имеет значение NULL. ppucKeyData имеет значение NULL или недопустимое значение. pbIsPassPhrase имеет значение NULL или недопустимо. pbPersistent имеет значение NULL. pvReserved не имеет значения NULL.
ERROR_INVALID_STATE	Ресурс не находится в правильном состоянии для выполнения запрошенной операции. Это может произойти, если беспроводная размещенная сеть была в процессе завершения работы.
ERROR_OUTOFMEMORY	Недостаточно места в хранилище для завершения этой операции.
ERROR_SERVICE_NOT_ACTIVE	Служба не запущена. Эта ошибка возвращается, если служба автонастройки WLAN не запущена.
Другое	Различные коды RPC и другие коды ошибок. Используйте FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки.

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

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

Вторичный ключ безопасности является парольной фразой, если значение, указываемое параметром pbIsPassPhrase , равно TRUE. Вторичный ключ безопасности является двоичным ключом, если значение, указываемое параметром pbIsPassPhrase , равно FALSE.

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

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

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

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

Если в данный момент не настроен дополнительный ключ безопасности, возвращаемое значение, указываемое параметром pdwKeyLength , будет равно нулю, а значение, возвращаемое в параметре ppucKeyData , будет иметь значение NULL. В этом случае значение, возвращаемое в параметрах pbIsPassPhrase и pbPersistent , будет бессмысленным.

Если функция WlanHostedNetworkQuerySecondaryKey завершается успешно, память, используемая для буфера в возвращаемом параметре ppucKeyData , должна быть освобождена после использования путем вызова функции WlanFreeMemory .

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

В 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