Функция WlanGetNetworkBssList (wlanapi.h)
Примечание
Некоторые сведения относятся к предварительной версии продукта, в которую перед коммерческим выпуском могут быть внесены существенные изменения. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.
Важно!
На этот 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 .
| Значение | Значение |
|---|---|
|
Сеть BSS инфраструктуры. |
|
Независимая сеть BSS (IBSS) (нерегламентированной сети). |
|
Любая сеть BSS. |
[in] bSecurityEnabled
Значение типа , указывающее, включена ли безопасность в сети. Этот параметр действителен, только если указан SSID сети для списка BSS (параметр pDot11Ssid не равен NULL).
pReserved
Зарезервировано для последующего использования. Этот параметр должен иметь значение NULL.
[out] ppWlanBssList
Указатель на хранилище для указателя, который получает возвращенный список записей BSS в структуре WLAN_BSS_LIST .
Буфер для возвращаемого WLAN_BSS_LIST выделяется функцией WlanGetNetworkBssList , если вызов выполнен успешно.
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение будет ERROR_SUCCESS.
Если функция завершается сбоем, возвращаемое значение может быть одним из следующих кодов возврата.
| Код возврата | Описание |
|---|---|
|
Дескриптор hClientHandle не найден в таблице дескрипторов. |
|
Неправильный параметр. Эта ошибка возвращается, если параметр hClientHandle, pInterfaceGuid или ppWlanBssList имеет значение NULL. Эта ошибка возвращается, если значение pReserved не равно NULL. Эта ошибка также возвращается, если hClientHandle, SSID, указанный в параметре pDot11Ssid , или тип BSS, указанный в параметре dot11BssType, является недопустимым . |
|
Радио, связанное с интерфейсом , отключено. Список BSS недоступен, если переключатель выключен. |
|
Недостаточно памяти для обработки этого запроса и выделения памяти для результатов запроса. |
|
Элемент не обнаружен. Эта ошибка возвращается, если не удалось найти GUID запрашиваемого интерфейса, указанного в параметре pInterfaceGuid . |
|
Запрос не поддерживается. Эта ошибка возвращается, если эта функция была вызвана из клиента Windows XP с пакетом обновления 3 (SP3) или API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2). Эта ошибка также возвращается, если служба автонастройки WLAN отключена. |
|
Служба автонастройки WLAN не запущена. |
|
Различные коды ошибок. |
Комментарии
Функция 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 |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по