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

Функция 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.

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

Замечания

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

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

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

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

Дополнительные сведения о IES PSD, включая обсуждение формата 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 может увеличить задержку до завершения проверки сети.

Требования

См. также

DOT11_SSID

WLAN_RAW_DATA

WlanEnumInterfaces

WlanGetAvailableNetworkList

WlanGetNetworkBssList

WlanRegisterNotification

WlanSetPsdIEDataList