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

Статья
10/19/2023

Примечание

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

Важно!

На этот API повлияют предстоящие изменения в поведении операционной системы, запланированные на осень 2024 года. Дополнительные сведения см. в статье Изменения в поведении API для Wi-Fi доступа и расположения.

Функция WlanGetNetworkBssList извлекает список записей набора базовых служб (BSS) беспроводной сети или сетей в заданном интерфейсе беспроводной локальной сети.

Синтаксис

DWORD WlanGetNetworkBssList(
  [in]       HANDLE            hClientHandle,
  [in]       const GUID        *pInterfaceGuid,
  [optional] const PDOT11_SSID pDot11Ssid,
  [in]       DOT11_BSS_TYPE    dot11BssType,
  [in]       BOOL              bSecurityEnabled,
             PVOID             pReserved,
  [out]      PWLAN_BSS_LIST    *ppWlanBssList
);

Параметры

[in] hClientHandle

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

[in] pInterfaceGuid

Указатель на GUID интерфейса беспроводной локальной сети для запроса.

Guid каждого интерфейса беспроводной локальной сети, включенного на локальном компьютере, можно определить с помощью функции WlanEnumInterfaces .

[optional] pDot11Ssid

Указатель на структуру DOT11_SSID , указывающую SSID сети, из которой запрашивается список BSS. Этот параметр является необязательным. Если задано значение NULL, возвращаемый список содержит все доступные записи BSS в интерфейсе беспроводной локальной сети.

Если указан указатель на структуру DOT11_SSID , длина SSID, указанная в элементе uSSIDLengthструктуры DOT11_SSID , должна быть меньше или равна DOT11_SSID_MAX_LENGTH , определенной в файле заголовка Wlantypes.h . Кроме того, параметру dot11BssType необходимо задать значение dot11_BSS_type_infrastructure или dot11_BSS_type_independent и указать параметр bSecurityEnabled .

[in] dot11BssType

Тип BSS сети. Этот параметр игнорируется, если SSID сети для списка BSS не указан (параметр pDot11Ssid имеет значение NULL).

Этот параметр может быть одним из следующих значений, определенных в перечислении DOT11_BSS_TYPE , определенном в файле заголовка Wlantypes.h .

Значение	Значение
dot11_BSS_type_infrastructure	Сеть BSS инфраструктуры.
dot11_BSS_type_independent	Независимая сеть BSS (IBSS) (нерегламентированной сети).
dot11_BSS_type_any	Любая сеть BSS.

[in] bSecurityEnabled

Значение типа , указывающее, включена ли безопасность в сети. Этот параметр действителен, только если указан SSID сети для списка BSS (параметр pDot11Ssid не равен NULL).

pReserved

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

[out] ppWlanBssList

Указатель на хранилище для указателя, который получает возвращенный список записей BSS в структуре WLAN_BSS_LIST .

Буфер для возвращаемого WLAN_BSS_LIST выделяется функцией WlanGetNetworkBssList , если вызов выполнен успешно.

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

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

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

Код возврата	Описание
ERROR_INVALID_HANDLE	Дескриптор hClientHandle не найден в таблице дескрипторов.
ERROR_INVALID_PARAMETER	Неправильный параметр. Эта ошибка возвращается, если параметр hClientHandle, pInterfaceGuid или ppWlanBssList имеет значение NULL. Эта ошибка возвращается, если значение pReserved не равно NULL. Эта ошибка также возвращается, если hClientHandle, SSID, указанный в параметре pDot11Ssid , или тип BSS, указанный в параметре dot11BssType, является недопустимым .
ERROR_NDIS_DOT11_POWER_STATE_INVALID	Радио, связанное с интерфейсом , отключено. Список BSS недоступен, если переключатель выключен.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно памяти для обработки этого запроса и выделения памяти для результатов запроса.
ERROR_NOT_FOUND	Элемент не обнаружен. Эта ошибка возвращается, если не удалось найти GUID запрашиваемого интерфейса, указанного в параметре pInterfaceGuid .
ERROR_NOT_SUPPORTED	Запрос не поддерживается. Эта ошибка возвращается, если эта функция была вызвана из клиента Windows XP с пакетом обновления 3 (SP3) или API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2). Эта ошибка также возвращается, если служба автонастройки WLAN отключена.
ERROR_SERVICE_NOT_ACTIVE	Служба автонастройки WLAN не запущена.
RPC_STATUS	Различные коды ошибок.

Функция WlanGetNetworkBssList извлекает базовый список наборов служб для каждой беспроводной сети или сетей, доступных в заданном интерфейсе. Список сведений, возвращаемых для каждой беспроводной сети, также содержит список элементов информации, возвращаемых каждой точкой доступа для сети BSS инфраструктуры или одноранговым сетевым элементом для независимой сети BSS (нерегламентированной сети). Сведения возвращаются в виде указателя на структуру WLAN_BSS_LIST в параметре ppWlanBssList . Структура WLAN_BSS_LIST содержит число элементов, за которым следует массив записей WLAN_BSS_ENTRY структуры.

Так как данные, возвращаемые функцией WlanGetNetworkBssList , отправляются точкой доступа для сети BSS инфраструктуры или одноранговым сетевым элементом для независимой сети BSS (нерегламентированной сети), возвращаемые сведения не должны быть доверенными. Элементы ulIeOffset и ulIeSize в структуре WLAN_BSS_ENTRY должны использоваться для определения размера большого двоичного объекта данных информационного элемента в WLAN_BSS_ENTRY структуре, а не данных в самом blob-объекте данных информационного элемента. Функция WlanGetNetworkBssList не проверяет, является ли какая-либо информация, возвращенная в blob-объекте данных элемента информации, на который указывает элемент ulIeOffset , является допустимым информационным элементом в соответствии со стандартами IEEE 802.11 для беспроводных локальных сетей.

Если указан параметр pDot11Ssid (не NULL), то для указанного параметра dot11BssType необходимо задать значение либо dot11_BSS_type_infrastructure для сети BSS инфраструктуры, либо dot11_BSS_type_independent для независимой сети BSS (нерегламентированной сети). Если параметр dot11BssType имеет значение dot11_BSS_type_any, то функция WlanGetNetworkBssList возвращает ERROR_SUCCESS но записи BSS не возвращаются.

Чтобы вернуть список всех сетей инфраструктуры BSS и независимых сетей BSS (нерегламентированных сетей) в интерфейсе беспроводной локальной сети, задайте для параметра pDot11Ssidзначение NULL. Если интерфейс беспроводной локальной сети также работает как беспроводная размещенная сеть, список BSS будет содержать запись для BSS, созданной для беспроводной сети.

Функция WlanGetNetworkBssList возвращает ERROR_SUCCESS, когда служба автонастройки WLAN возвращает пустой список BSS. Приложение, которое вызывает функцию WlanGetNetworkBssList, должно проверка, что член dwNumberOfItemsWLAN_BSS_LIST, на который указывает параметр ppWlanBssList, не равен нулю, прежде чем обращаться к члену wlanBssEntries[0] в WLAN_BSS_LIST структуре.

Функция WlanGetNetworkBssList выделяет память для базового списка наборов служб, который возвращается в буфере, на который указывает параметр ppWlanBssList при успешном выполнении функции. Память, используемая для буфера, на который указывает параметр ppWlanBssList , должна быть освобождена путем вызова функции WlanFreeMemory после того, как буфер больше не нужен.

Требования

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