WlanRegisterNotification function (wlanapi.h)
The WlanRegisterNotification function is used to register and unregister notifications on all wireless interfaces.
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 );
The client's session handle, obtained by a previous call to the WlanOpenHandle function.
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.
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.
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.
Reserved for future use. Must be set to NULL.
[out, optional] pdwPrevNotifSource
A pointer to the previously registered notification sources.
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.
||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.|
||Various error codes.|
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.
Do not 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), 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, do not 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.
|Minimum supported client||Windows Vista, Windows XP with SP3 [desktop apps only]|
|Minimum supported server||Windows Server 2008 [desktop apps only]|
|Header||wlanapi.h (include Wlanapi.h)|
|Redistributable||Wireless LAN API for Windows XP with SP2|