WlanRegisterNotification function (wlanapi.h)

Important

Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

The WlanRegisterNotification function is used to register and unregister notifications on all wireless interfaces.

Syntax

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
);

Parameters

[in] hClientHandle

The client's session handle, obtained by a previous call to the WlanOpenHandle function.

[in] dwNotifSource

The notification sources to be registered. These flags may be combined. When this parameter is set to WLAN_NOTIFICATION_SOURCE_NONE, WlanRegisterNotification unregisters notifications on all wireless interfaces.

The possible values for this parameter are defined in the Wlanapi.h and L2cmn.h header files.

The following table shows possible values.

Value Meaning
WLAN_NOTIFICATION_SOURCE_NONE
Unregisters notifications.
WLAN_NOTIFICATION_SOURCE_ALL
Registers for all notifications available on the version of the operating system, including those generated by the 802.1X module.

For Windows XP with SP3 and Wireless LAN API for Windows XP with SP2, setting dwNotifSource to WLAN_NOTIFICATION_SOURCE_ALL is functionally equivalent to setting dwNotifSource to WLAN_NOTIFICATION_SOURCE_ACM.

WLAN_NOTIFICATION_SOURCE_ACM
Registers for notifications generated by the auto configuration module.

Windows XP with SP3 and Wireless LAN API for Windows XP with SP2:  Only the wlan_notification_acm_connection_complete and wlan_notification_acm_disconnected notifications are available.

WLAN_NOTIFICATION_SOURCE_HNWK
Registers for notifications generated by the wireless Hosted Network. This notification source is available on Windows 7 and on Windows Server 2008 R2 with the Wireless LAN Service installed.
WLAN_NOTIFICATION_SOURCE_ONEX
Registers for notifications generated by 802.1X.
WLAN_NOTIFICATION_SOURCE_MSM
Registers for notifications generated by MSM.

If the WLAN_NOTIFICATION_SOURCE_MSM flag is set in dwNotifSource, then the wiFiControl device capability is required (see App capability declarations). If that capability is not granted, then the function returns ERROR_ACCESS_DENIED. Requesting the wiFiControl device capability will require consent from the user regarding access to location. For more info, see Changes to API behavior for Wi-Fi access and location.

Windows XP with SP3 and Wireless LAN API for Windows XP with SP2:  This value is not supported.

WLAN_NOTIFICATION_SOURCE_SECURITY
Registers for notifications generated by the security module.

No notifications are currently defined for WLAN_NOTIFICATION_SOURCE_SECURITY.

Windows XP with SP3 and Wireless LAN API for Windows XP with SP2:  This value is not supported.

WLAN_NOTIFICATION_SOURCE_IHV
Registers for notifications generated by independent hardware vendors (IHV).

Windows XP with SP3 and Wireless LAN API for Windows XP with SP2:  This value is not supported.

WLAN_NOTIFICATION_SOURCE_DEVICE_SERVICE
Registers for notifications generated by device services.

Windows XP with SP3 and Wireless LAN API for Windows XP with SP2:  This parameter must be set to WLAN_NOTIFICATION_SOURCE_NONE, WLAN_NOTIFICATION_SOURCE_ALL, or WLAN_NOTIFICATION_SOURCE_ACM.

[in] bIgnoreDuplicate

Specifies whether duplicate notifications will be ignored. If set to TRUE, a notification will not be sent to the client if it is identical to the previous one.

Windows XP with SP3 and Wireless LAN API for Windows XP with SP2:  This parameter is ignored.

[in, optional] funcCallback

A WLAN_NOTIFICATION_CALLBACK type that defines the type of notification callback function.

This parameter can be NULL if the dwNotifSource parameter is set to WLAN_NOTIFICATION_SOURCE_NONE to unregister notifications on all wireless interfaces,

[in, optional] pCallbackContext

A pointer to the client context that will be passed to the callback function with the notification.

[in] pReserved

Reserved for future use. Must be set to NULL.

[out, optional] pdwPrevNotifSource

A pointer to the previously registered notification sources.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value may be one of the following return codes.

If the WLAN_NOTIFICATION_SOURCE_MSM flag is set in dwNotifSource, then the wiFiControl device capability is required (see App capability declarations). If that capability is not granted, then the function returns ERROR_ACCESS_DENIED. Requesting the wiFiControl device capability will require consent from the user regarding access to location. For more info, see Changes to API behavior for Wi-Fi access and location.

Return code Description
ERROR_INVALID_PARAMETER
A parameter is incorrect. This error is returned if hClientHandle is NULL or not valid or if pReserved is not NULL.
ERROR_INVALID_HANDLE
The handle hClientHandle was not found in the handle table.
ERROR_NOT_ENOUGH_MEMORY
Failed to allocate memory for the query results.
ERROR_ACCESS_DENIED
If the WLAN_NOTIFICATION_SOURCE_MSM flag is set in dwNotifSource, then the wiFiControl device capability is required (see App capability declarations. If that capability is not granted, then the function returns ERROR_ACCESS_DENIED. Requesting the wiFiControl device capability will require consent from the user regarding access to location. For more info, see Changes to API behavior for Wi-Fi access and location.
RPC_STATUS
Various error codes.

Remarks

The WlanRegisterNotification is used by an application to register and unregister notifications on all wireless interfaces. When registering for notifications, an application must provide a callback function pointed to by the funcCallback parameter. The prototype for this callback function is the WLAN_NOTIFICATION_CALLBACK. This callback function will receive notifications that have been registered for in the dwNotifSource parameter passed to the WlanRegisterNotification function. The callback function is called with a pointer to a WLAN_NOTIFICATION_DATA structure as the first parameter that contains detailed information on the notification. The callback function also receives a second parameter that contains a pointer to the client context passed in the pCallbackContext parameter to the WlanRegisterNotification function.

The WlanRegisterNotification function will return an error if dwNotifSource is a value other than WLAN_NOTIFICATION_SOURCE_NONE and the client fails to provide a callback function.

Once registered, the callback function will be called whenever a notification is available until the client unregisters or closes the handle.

Any registration to receive notifications caused by this function would be automatically undone if the calling application closes its calling handle (by calling WlanCloseHandle with the hClientHandle parameter) or if the process ends.

Don't call WlanRegisterNotification from a callback function. If the client is in the middle of a notification callback when WlanRegisterNotification is called with dwNotifSource set to WLAN_NOTIFICATION_SOURCE_NONE (that is, when the client is unregistering from notifications), then WlanRegisterNotification will wait for the callback to finish before returning a value. Calling this function inside a callback function will result in the call never completing. If both the callback function and the thread that unregisters from notifications try to acquire the same lock, a deadlock may occur. In addition, don't call WlanRegisterNotification from the DllMain function in an application DLL. This could also cause a deadlock.

An application can time out and query the current interface state instead of waiting for a notification.

Windows XP with SP3 and Wireless LAN API for Windows XP with SP2: Notifications are handled by the Netman service. If the Netman service is disabled or unavailable, notifications will not be received. If a notification is not received within a reasonable period of time, an application should time out and query the current interface state.

Requirements

Requirement Value
Minimum supported client Windows Vista, Windows XP with SP3 [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header wlanapi.h (include Wlanapi.h)
Library Wlanapi.lib
DLL Wlanapi.dll
Redistributable Wireless LAN API for Windows XP with SP2

See also

ONEX_NOTIFICATION_TYPE

WLAN_HOSTED_NETWORK_NOTIFICATION_CODE

WLAN_NOTIFICATION_ACM

WLAN_NOTIFICATION_CALLBACK

WLAN_NOTIFICATION_DATA

WLAN_NOTIFICATION_MSM

WlanCloseHandle

WlanRegisterVirtualStationNotification