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 |
|---|---|
|
Unregisters notifications. |
|
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. |
|
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. |
|
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. |
|
Registers for notifications generated by 802.1X. |
|
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. |
|
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. |
|
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. |
|
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 |
|---|---|
|
A parameter is incorrect. This error is returned if hClientHandle is NULL or not valid or if pReserved is not NULL. |
|
The handle hClientHandle was not found in the handle table. |
|
Failed to allocate memory for the query results. |
|
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. |
|
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 |