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

Статья
02/05/2024

Важно!

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

Функция WlanRegisterNotification используется для регистрации и отмены регистрации уведомлений на всех беспроводных интерфейсах.

Синтаксис

DWORD WlanRegisterNotification(
  [in]            HANDLE                     hClientHandle,
  [in]            DWORD                      dwNotifSource,
  [in]            BOOL                       bIgnoreDuplicate,
  [in, optional]  WLAN_NOTIFICATION_CALLBACK funcCallback,
  [in, optional]  PVOID                      pCallbackContext,
  [in]            PVOID                      pReserved,
  [out, optional] PDWORD                     pdwPrevNotifSource
);

Параметры

[in] hClientHandle

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

[in] dwNotifSource

Источники уведомлений, которые необходимо регистрировать. Эти флаги могут быть объединены. Если для этого параметра задано значение WLAN_NOTIFICATION_SOURCE_NONE, WlanRegisterNotification отменяет регистрацию уведомлений на всех беспроводных интерфейсах.

Возможные значения для этого параметра определяются в файлах заголовков Wlanapi.h и L2cmn.h .

В следующей таблице показаны возможные значения.

Значение	Значение
WLAN_NOTIFICATION_SOURCE_NONE	Отмена регистрации уведомлений.
WLAN_NOTIFICATION_SOURCE_ALL	Регистрирует все уведомления, доступные в версии операционной системы, включая уведомления, созданные модулем 802.1X. Для Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2) установка параметра dwNotifSource в WLAN_NOTIFICATION_SOURCE_ALL функционально эквивалентна параметру dwNotifSourceзначение WLAN_NOTIFICATION_SOURCE_ACM.
WLAN_NOTIFICATION_SOURCE_ACM	Регистрирует уведомления, созданные модулем автоматической настройки. Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2): Доступны только уведомления wlan_notification_acm_connection_complete и wlan_notification_acm_disconnected.
WLAN_NOTIFICATION_SOURCE_HNWK	Регистрирует уведомления, созданные беспроводной размещенной сетью. Этот источник уведомлений доступен в Windows 7 и Windows Server 2008 R2 с установленной службой беспроводной локальной сети.
WLAN_NOTIFICATION_SOURCE_ONEX	Регистрирует уведомления, созданные 802.1X.
WLAN_NOTIFICATION_SOURCE_MSM	Регистрирует уведомления, созданные MSM. Если флаг WLAN_NOTIFICATION_SOURCE_MSM установлен в dwNotifSource, требуется возможность устройства wiFiControl (см . объявления возможностей приложений). Если эта возможность не предоставляется, функция возвращает ERROR_ACCESS_DENIED. Для запроса возможности устройства wiFiControl потребуется согласие пользователя на доступ к расположению. Дополнительные сведения см. в статье Изменения в поведении API для Wi-Fi доступа и расположения. Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2): Это значение не поддерживается.
WLAN_NOTIFICATION_SOURCE_SECURITY	Регистрирует уведомления, созданные модулем безопасности. Уведомления для WLAN_NOTIFICATION_SOURCE_SECURITY в настоящее время не определены. Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2): Это значение не поддерживается.
WLAN_NOTIFICATION_SOURCE_IHV	Регистрирует уведомления, созданные независимыми поставщиками оборудования (IHV). Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2): Это значение не поддерживается.
WLAN_NOTIFICATION_SOURCE_DEVICE_SERVICE	Регистрирует уведомления, созданные службами устройств.

Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2): Для этого параметра необходимо задать значение WLAN_NOTIFICATION_SOURCE_NONE, WLAN_NOTIFICATION_SOURCE_ALL или WLAN_NOTIFICATION_SOURCE_ACM.

[in] bIgnoreDuplicate

Указывает, будут ли игнорироваться повторяющиеся уведомления. Если задано значение TRUE, уведомление не будет отправлено клиенту, если оно идентично предыдущему.

Windows XP с пакетом обновления 3 (SP3) и API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2): Этот параметр игнорируется.

[in, optional] funcCallback

Тип WLAN_NOTIFICATION_CALLBACK , определяющий тип функции обратного вызова уведомления.

Этот параметр может иметь значение NULL , если для параметра dwNotifSource задано значение WLAN_NOTIFICATION_SOURCE_NONE отмены регистрации уведомлений на всех беспроводных интерфейсах.

[in, optional] pCallbackContext

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

[in] pReserved

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

[out, optional] pdwPrevNotifSource

Указатель на ранее зарегистрированные источники уведомлений.

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

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

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

Если флаг WLAN_NOTIFICATION_SOURCE_MSM установлен в dwNotifSource, требуется возможность устройства wiFiControl (см . объявления возможностей приложений). Если эта возможность не предоставляется, функция возвращает ERROR_ACCESS_DENIED. Для запроса возможности устройства wiFiControl потребуется согласие пользователя на доступ к расположению. Дополнительные сведения см. в статье Изменения в поведении API для Wi-Fi доступа и расположения.

Код возврата	Описание
ERROR_INVALID_PARAMETER	Неправильный параметр. Эта ошибка возвращается, если hClientHandle имеет значение NULL или недопустимо, или если pReserved не равно NULL.
ERROR_INVALID_HANDLE	Дескриптор hClientHandle не найден в таблице дескрипторов.
ERROR_NOT_ENOUGH_MEMORY	Не удалось выделить память для результатов запроса.
ERROR_ACCESS_DENIED	Если флаг WLAN_NOTIFICATION_SOURCE_MSM установлен в dwNotifSource, то требуется возможность устройства wiFiControl (см. статью Объявления возможностей приложений). Если эта возможность не предоставляется, функция возвращает ERROR_ACCESS_DENIED. Для запроса возможности устройства wiFiControl потребуется согласие пользователя на доступ к расположению. Дополнительные сведения см. в статье Изменения в поведении API для Wi-Fi доступа и расположения.
RPC_STATUS	Различные коды ошибок.

WlanRegisterNotification используется приложением для регистрации и отмены регистрации уведомлений на всех беспроводных интерфейсах. При регистрации для уведомлений приложение должно предоставить функцию обратного вызова, на которую указывает параметр funcCallback . Прототипом этой функции обратного вызова является WLAN_NOTIFICATION_CALLBACK. Эта функция обратного вызова будет получать уведомления, зарегистрированные в параметре dwNotifSource , переданном функции WlanRegisterNotification . Функция обратного вызова вызывается с указателем на структуру WLAN_NOTIFICATION_DATA в качестве первого параметра, содержащего подробные сведения об уведомлении. Функция обратного вызова также получает второй параметр, содержащий указатель на контекст клиента, переданный в параметре pCallbackContext в функцию WlanRegisterNotification .

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

После регистрации функция обратного вызова будет вызываться при каждом появлении уведомления, пока клиент не отменит регистрацию или не закроет дескриптор.

Любая регистрация для получения уведомлений, вызванных этой функцией, будет автоматически отменена, если вызывающее приложение закрывает свой вызывающий дескриптор (путем вызова WlanCloseHandle с параметром hClientHandle ) или если процесс завершается.

Не вызывайте WlanRegisterNotification из функции обратного вызова. Если клиент находится в середине обратного вызова уведомления при вызове WlanRegisterNotification с параметромdwNotifSource, для WLAN_NOTIFICATION_SOURCE_NONE (т. е. когда клиент отменяет регистрацию в уведомлениях), WlanRegisterNotification будет ожидать завершения обратного вызова, прежде чем возвращать значение. Вызов этой функции внутри функции обратного вызова приведет к тому, что вызов никогда не завершится. Если функция обратного вызова и поток, отменяющий регистрацию в уведомлениях, пытаются получить одну и ту же блокировку, может возникнуть взаимоблокировка. Кроме того, не вызывайте WlanRegisterNotification из функции DllMain в библиотеке DLL приложения. Это также может привести к взаимоблокировки.

Приложение может запросить текущее состояние интерфейса, а не ожидать уведомления.

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

Требования

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