wlanapi.h (wlanregisterNotification 函数)

项目
03/04/2024

重要

某些信息与预发行产品相关，在商业发布之前，该产品可能会进行实质性修改。对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。

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 模块生成的通知。对于 SP3 的 Windows XP 和 SP2 的 Windows XP 无线 LAN API，将 dwNotifSource 设置为 WLAN_NOTIFICATION_SOURCE_ALL 在功能上等效于将 dwNotifSource 设置为 WLAN_NOTIFICATION_SOURCE_ACM。
WLAN_NOTIFICATION_SOURCE_ACM	注册自动配置模块生成的通知。具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API：只有wlan_notification_acm_connection_complete和wlan_notification_acm_disconnected通知可用。
WLAN_NOTIFICATION_SOURCE_HNWK	注册无线托管网络生成的通知。此通知源在安装了无线 LAN 服务的 Windows 7 和 Windows Server 2008 R2 上可用。
WLAN_NOTIFICATION_SOURCE_ONEX	注册 802.1X 生成的通知。
WLAN_NOTIFICATION_SOURCE_MSM	注册 MSM 生成的通知。如果在 dwNotifSource 中设置了WLAN_NOTIFICATION_SOURCE_MSM标志，则需要 wiFiControl 设备功能 (请参阅应用功能声明) 。如果未授予该功能，则该函数将返回 ERROR_ACCESS_DENIED。请求 wiFiControl 设备功能需要用户同意访问位置。有关详细信息，请参阅更改 api 行为的 Wi-Fi 访问和位置。具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API：不支持此值。
WLAN_NOTIFICATION_SOURCE_SECURITY	注册安全模块生成的通知。当前未为 WLAN_NOTIFICATION_SOURCE_SECURITY定义通知。具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API：不支持此值。
WLAN_NOTIFICATION_SOURCE_IHV	注册独立硬件供应商 (IHV) 生成的通知。具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API：不支持此值。
WLAN_NOTIFICATION_SOURCE_DEVICE_SERVICE	注册设备服务生成的通知。

具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API： 此参数必须设置为 WLAN_NOTIFICATION_SOURCE_NONE、WLAN_NOTIFICATION_SOURCE_ALL 或 WLAN_NOTIFICATION_SOURCE_ACM。

[in] bIgnoreDuplicate

指定是否忽略重复通知。如果设置为 TRUE，则不会向客户端发送通知（如果通知与上一个通知相同）。

具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API： 此参数将被忽略。

[in, optional] funcCallback

定义通知回调函数类型的 WLAN_NOTIFICATION_CALLBACK 类型。

如果 dwNotifSource 参数设置为 WLAN_NOTIFICATION_SOURCE_NONE以在所有无线接口上取消注册通知，则此参数可以为 NULL。

[in, optional] pCallbackContext

指向客户端上下文的指针，该指针将传递给带有通知的回调函数。

[in] pReserved

保留供将来使用。必须设置为 NULL。

[out, optional] pdwPrevNotifSource

指向以前注册的通知源的指针。

返回值

如果函数成功，则返回值为 ERROR_SUCCESS。

如果函数失败，则返回值可能是以下返回代码之一。

如果在 dwNotifSource 中设置了WLAN_NOTIFICATION_SOURCE_MSM标志，则需要 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	如果在 dwNotifSource 中设置了WLAN_NOTIFICATION_SOURCE_MSM标志，则需要 wiFiControl 设备功能， (请参阅应用功能声明。如果未授予该功能，则该函数将返回 ERROR_ACCESS_DENIED。请求 wiFiControl 设备功能需要用户同意访问位置。有关详细信息，请参阅更改 api 行为的 Wi-Fi 访问和位置。
RPC_STATUS	各种错误代码。

注解

应用程序使用 WlanRegisterNotification 在所有无线接口上注册和取消注册通知。注册通知时，应用程序必须提供 funcCallback 参数指向的回调函数。此回调函数的原型是 WLAN_NOTIFICATION_CALLBACK。此回调函数将接收已在传递给 WlanRegisterNotification 函数的 dwNotifSource 参数中注册的通知。回调函数使用指向 WLAN_NOTIFICATION_DATA 结构的指针调用，作为包含通知详细信息的第一个参数。回调函数还接收第二个参数，该参数包含指向客户端上下文的指针，该指针在 pCallbackContext 参数中传递给 WlanRegisterNotification 函数。

如果 dwNotifSource 不是 WLAN_NOTIFICATION_SOURCE_NONE 并且客户端无法提供回调函数，则 WlanRegisterNotification 函数将返回错误。

注册后，每当通知可用时，都会调用回调函数，直到客户端注销或关闭句柄。

如果调用应用程序通过使用 hClientHandle 参数) 调用 WlanCloseHandle 关闭其调用句柄 (或进程结束，则会自动撤消由此函数引起的任何接收通知的注册。

不要从回调函数调用 WlanRegisterNotification 。如果在调用 wlanRegisterNotification 时客户端处于通知回调的中间，且 dwNotifSource 设置为 WLAN_NOTIFICATION_SOURCE_NONE (即，当客户端从通知) 注销时， WlanRegisterNotification 将等待回调完成，然后返回值。在回调函数中调用此函数将导致调用永远不会完成。如果回调函数和从通知中注销的线程都尝试获取同一锁，则可能会出现死锁。此外，不要从应用程序 DLL 中的 DllMain 函数调用 WlanRegisterNotification。这也可能导致死锁。

应用程序可以超时并查询当前接口状态，而不是等待通知。

具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API： 通知由 Netman 服务处理。如果 Netman 服务已禁用或不可用，则不会收到通知。如果在合理的时间段内未收到通知，应用程序应超时并查询当前接口状态。

要求

要求	值
最低受支持的客户端	Windows Vista、Windows XP 和 SP3 [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	wlanapi.h (包括 Wlanapi.h)
Library	Wlanapi.lib
DLL	Wlanapi.dll
可再发行组件	适用于 Windows XP 的无线 LAN API SP2