Export (0) Print
Expand All
Expand Minimize

WlanRegisterNotification function

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

Syntax


DWORD WINAPI WlanRegisterNotification(
  _In_        HANDLE hClientHandle,
  _In_        DWORD dwNotifSource,
  _In_        BOOL bIgnoreDuplicate,
  _In_opt_    WLAN_NOTIFICATION_CALLBACK  funcCallback,
  _In_opt_    PVOID pCallbackContext,
  _Reserved_  PVOID pReserved,
  _Out_opt_   PDWORD pdwPrevNotifSource
);

Parameters

hClientHandle [in]

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

dwNotifSource [in]

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.

ValueMeaning
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.

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.

 

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.

bIgnoreDuplicate [in]

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.

funcCallback [in, optional]

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,

pCallbackContext [in, optional]

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

pReserved [in]

Reserved for future use. Must be set to NULL.

pdwPrevNotifSource [out, optional]

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.

Return codeDescription
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.

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.

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.

Requirements

Minimum supported client

Windows Vista, Windows XP with SP3 [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Redistributable

Wireless LAN API for Windows XP with SP2

Header

Wlanapi.h (include Wlanapi.h)

Library

Wlanapi.lib

DLL

Wlanapi.dll

See also

ONEX_NOTIFICATION_TYPE
WLAN_NOTIFICATION_ACM
WLAN_NOTIFICATION_CALLBACK
WLAN_NOTIFICATION_DATA
WLAN_HOSTED_NETWORK_NOTIFICATION_CODE
WLAN_NOTIFICATION_MSM
WlanCloseHandle
WlanRegisterVirtualStationNotification

 

 

Community Additions

ADD
Show:
© 2014 Microsoft