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

Статья
10/19/2023

Примечание

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

Важно!

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

Функция WlanScan запрашивает сканирование доступных сетей в указанном интерфейсе.

Синтаксис

DWORD WlanScan(
  [in]           HANDLE               hClientHandle,
  [in]           const GUID           *pInterfaceGuid,
  [in, optional] const PDOT11_SSID    pDot11Ssid,
  [in, optional] const PWLAN_RAW_DATA pIeData,
                 PVOID                pReserved
);

Параметры

[in] hClientHandle

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

[in] pInterfaceGuid

GUID запрашиваемого интерфейса.

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

[in, optional] pDot11Ssid

Указатель на структуру DOT11_SSID , указывающую SSID проверяемой сети. Этот параметр является необязательным. Если задано значение NULL, возвращаемый список содержит все доступные сети. Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2): Этот параметр должен иметь значение NULL.

[in, optional] pIeData

Указатель на информационный элемент для включения в запросы пробы. Этот параметр указывает на WLAN_RAW_DATA структуру, которая может включать сведения о доступности подготовки клиентов и требования к проверке подлинности 802.1X. Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2): Этот параметр должен иметь значение NULL.

pReserved

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

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

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

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

Код возврата	Описание
ERROR_INVALID_PARAMETER	hClientHandle имеет значение NULL или недопустимое значение, pInterfaceGuid имеет значение NULL или pReserved не равно NULL.
ERROR_INVALID_HANDLE	Дескриптор hClientHandle не найден в таблице дескрипторов.
RPC_STATUS	Различные коды ошибок.
ERROR_NOT_ENOUGH_MEMORY	Не удалось выделить память для результатов запроса.

Функция WlanScan запрашивает, чтобы собственный драйвер беспроводной локальной сети 802.11 проверял наличие доступных беспроводных сетей. Драйвер может отправлять или не отправлять запросы пробы (активное сканирование) в зависимости от его реализации и значений, передаваемых в параметрах pDot11Ssid и pIeData .

Если параметр pIeData не имеет значение NULL, драйвер будет отправлять запросы пробы во время проверки. Запросы пробы включают информационный элемент (IE), на который указывает параметр pIeData . Например, IE Wi-Fi protected Setup (WPS) можно включить в запросы пробы для обнаружения точек доступа с поддержкой WPS. Буфер, на который указывает параметр pIeData, должен содержать полный IE, начиная с идентификатора элемента.

Параметр pIeData , передаваемый в функцию WlanScan, может содержать указатель на необязательную структуру WLAN_RAW_DATA , содержащую запись данных IE обнаружения служб близкого взаимодействия (PSD).

При использовании для хранения PSD IE константа DOT11_PSD_IE_MAX_DATA_SIZE , определенная в файле заголовка Wlanapi.h , является максимальным значением члена dwDataSize .

Константа	Значение	Описание
DOT11_PSD_IE_MAX_DATA_SIZE	240	Максимальный размер данных (в байтах) записи данных PSD IE.

Дополнительные сведения о PSD IEs, включая обсуждение формата PSD IE, см. в разделе Функция WlanSetPsdIEDataList .

При вызове функции WlanScan собственный драйвер беспроводной локальной сети 802.11 может очистить текущий список доступных беспроводных сетей перед началом сканирования. Приложения не должны предполагать, что вызов функции WlanScan добавит в существующий список доступных беспроводных сетей, возвращенных функциями WlanGetNetworkBssList или WlanGetAvailableNetworkList из предыдущих проверок.

Функция WlanScan возвращает немедленно. Чтобы получать уведомления о завершении проверки сети, клиент в Windows Vista и более поздних версиях должен зарегистрироваться для получения уведомлений, вызвав WlanRegisterNotification. Параметр dwNotifSource , передаваемый в функцию WlanRegisterNotification , должен иметь WLAN_NOTIFICATION_SOURCE_ACM бит для регистрации уведомлений, созданных модулем автоматической настройки. Драйверы беспроводной сети, соответствующие требованиям к логотипу Windows, должны выполнять запрос функции WlanScan за 4 секунды.

Служба беспроводной локальной сети не отправляет уведомления при изменении доступных беспроводных сетей. Служба беспроводной локальной сети не отслеживает изменения в списке доступных сетей при нескольких проверках. Текущее поведение по умолчанию заключается в том, что служба беспроводной локальной сети запрашивает только драйвер беспроводного интерфейса для сканирования беспроводных сетей каждые 60 секунд, а в некоторых случаях (если она уже подключена к беспроводной сети) служба беспроводной локальной сети вообще не запрашивает сканирование. Функция WlanScan может использоваться приложением для отслеживания изменений в беспроводной сети. Сначала приложение должно зарегистрироваться для получения уведомлений WLAN_NOTIFICATION_SOURCE_ACM. Затем можно вызвать функцию WlanScan для запуска сканирования. Затем приложение должно подождать, чтобы получить уведомление о wlan_notification_acm_scan_complete или время ожидания через 4 секунды. Затем приложение может вызвать функцию WlanGetNetworkBssList или WlanGetAvailableNetworkList , чтобы получить список доступных беспроводных сетей. Этот процесс можно периодически повторять, когда приложение отслеживает изменения доступных беспроводных сетей.

Функция WlanScan возвращается немедленно и не предоставляет уведомления о завершении сканирования в Windows XP с пакетом обновления 3 (SP3) или API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2).

Так как беспроводному интерфейсу становится сложнее отправлять и получать пакеты данных во время сканирования, функция WlanScan может увеличить задержку до завершения сканирования сети.

Требования

Требование	Значение
Минимальная версия клиента	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)