WLAN_NOTIFICATION_DATA structure
The WLAN_NOTIFICATION_DATA structure contains information provided when receiving notifications.
Syntax
typedef struct _WLAN_NOTIFICATION_DATA {
DWORD NotificationSource;
DWORD NotificationCode;
GUID InterfaceGuid;
DWORD dwDataSize;
PVOID pData;
} WLAN_NOTIFICATION_DATA, *PWLAN_NOTIFICATION_DATA;
Members
NotificationSource
A value that indicates the source of the notification.
The possible values for this member are defined in the Wlanapai.h header file to values defined in the L2cmn.h header file.
Windows XP with SP3 and Wireless LAN API for Windows XP with SP2: This parameter is set to WLAN_NOTIFICATION_SOURCE_NONE, WLAN_NOTIFICATION_SOURCE_ALL, or WLAN_NOTIFICATION_SOURCE_ACM.
| Value | Meaning |
|---|---|
| WLAN_NOTIFICATION_SOURCE_NONE 0 | A notification generated by an unknown source. |
| WLAN_NOTIFICATION_SOURCE_ONEX 0X00000004 | A notification generated by the 802.1X module. For more information on these notifications, see the ONEX_NOTIFICATION_TYPE enumeration reference. |
| WLAN_NOTIFICATION_SOURCE_ACM 0X00000008 | A notification generated by the auto configuration module. For more information on these notifications, see the WLAN_NOTIFICATION_ACM enumeration reference. |
| WLAN_NOTIFICATION_SOURCE_MSM 0X00000010 | A notification generated by the media specific module (MSM). For more information on these notifications, see the WLAN_NOTIFICATION_MSM enumeration reference. |
| WLAN_NOTIFICATION_SOURCE_SECURITY 0X00000020 | A notification generated by the security module. No notifications are currently defined for WLAN_NOTIFICATION_SOURCE_SECURITY. |
| WLAN_NOTIFICATION_SOURCE_IHV 0X00000040 | A notification generated by independent hardware vendors (IHV). |
| WLAN_NOTIFICATION_SOURCE_HNWK 0X00000080 | A notification generated by the wireless Hosted Network. For more information on these notifications, see the WLAN_HOSTED_NETWORK_NOTIFICATION_CODE enumeration reference. This notification source is available on Windows 7 and on Windows Server 2008 R2 with the Wireless LAN Service installed. |
| WLAN_NOTIFICATION_SOURCE_ALL 0X0000FFFF | A notification generated by the 802.1X module. |
NotificationCode
The type of notification. The value of this member indicates what type of associated data will be present in the value pointed to by the pData member.
This member can be a ONEX_NOTIFICATION_TYPE, WLAN_NOTIFICATION_ACM, WLAN_NOTIFICATION_MSM, or WLAN_HOSTED_NETWORK_NOTIFICATION_CODE enumeration value.
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.
The following values are possible when the NotificationSource member is equal to WLAN_NOTIFICATION_SOURCE_ONEX.
| Value | Meaning |
|---|---|
| OneXNotificationTypeResultUpdate 1 | A status change occurred for 802.1X authentication. The pData member points to a ONEX_RESULT_UPDATE_DATA structure that identifies the 802.1X status change. |
| OneXNotificationTypeAuthRestarted 2 | The 802.1X authentication process was restarted. The pData member points to a ONEX_AUTH_RESTART_REASON enumeration value that identifies the reason that 802.1X authentication was restarted. |
| OneXNotificationTypeEventInvalid 3 |
The following values are possible when the NotificationSource member is equal to WLAN_NOTIFICATION_SOURCE_ACM.
| Value | Meaning |
|---|---|
| wlan_notification_acm_autoconf_enabled 0X00000001 | Autoconfiguration is enabled. |
| wlan_notification_acm_autoconf_disabled 0X00000002 | Autoconfiguration is disabled. |
| wlan_notification_acm_background_scan_enabled 0X00000003 | Background scans are enabled. |
| wlan_notification_acm_background_scan_disabled 0X00000004 | Background scans are disabled. |
| wlan_notification_acm_bss_type_change 0X00000005 | The BSS type for an interface has changed. The pData member points to a DOT11_BSS_TYPE enumeration value that identifies the new basic service set (BSS) type. |
| wlan_notification_acm_power_setting_change 0X00000006 | The power setting for an interface has changed. The pData member points to a WLAN_POWER_SETTING enumeration value that identifies the new power setting of an interface. |
| wlan_notification_acm_scan_complete 0X00000007 | A scan for networks has completed. |
| wlan_notification_acm_scan_fail 0X00000008 | A scan for connectable networks failed. The pData member points to a WLAN_REASON_CODE data type value that identifies the reason the WLAN operation failed. |
| wlan_notification_acm_connection_start 0X00000009 | A connection has started to a network in range. The pData member points to a WLAN_CONNECTION_NOTIFICATION_DATA structure that identifies the network information for the connection attempt. |
| wlan_notification_acm_connection_complete 0X0000000a | A connection has completed. The pData member points to a WLAN_CONNECTION_NOTIFICATION_DATA structure that identifies the network information for the connection attempt that completed. The connection succeeded if the wlanReasonCode in WLAN_CONNECTION_NOTIFICATION_DATA is WLAN_REASON_CODE_SUCCESS. Otherwise, the connection has failed. |
| wlan_notification_acm_connection_attempt_fail 0X0000000b | A connection attempt has failed. A connection consists of one or more connection attempts. An application may receive zero or more wlan_notification_acm_connection_attempt_fail notifications between receiving the wlan_notification_acm_connection_start notification and the wlan_notification_acm_connection_complete notification. The pData member points to a WLAN_CONNECTION_NOTIFICATION_DATA structure that identifies the network information for the connection attempt that failed. |
| wlan_notification_acm_filter_list_change 0X0000000c | A change in the filter list has occurred, either through group policy or a call to the WlanSetFilterList function. An application can call the WlanGetFilterList function to retrieve the new filter list. |
| wlan_notification_acm_interface_arrival 0X0000000d | A wireless LAN interface is been added to or enabled on the local computer. |
| wlan_notification_acm_interface_removal 0X0000000e | A wireless LAN interface has been removed or disabled on the local computer. |
| wlan_notification_acm_profile_change 0X0000000f | A change in a profile or the profile list has occurred, either through group policy or by calls to Native Wifi functions. An application can call the WlanGetProfileList and WlanGetProfile functions to retrieve the updated profiles. The interface on which the profile list changes is identified by the InterfaceGuid member. |
| wlan_notification_acm_profile_name_change 0X00000010 | A profile name has changed, either through group policy or by calls to Native Wifi functions. The pData member points to a buffer that contains two NULL-terminated WCHAR strings, the old profile name followed by the new profile name. |
| wlan_notification_acm_profiles_exhausted 0X00000011 | All profiles were exhausted in an attempt to autoconnect. |
| wlan_notification_acm_network_not_available 0X00000012 | The wireless service cannot find any connectable network after a scan. The interface on which no connectable network is found is identified by identified by the InterfaceGuid member. |
| wlan_notification_acm_network_available 0X00000013 | The wireless service found a connectable network after a scan, the interface was in the disconnected state, and there is no compatible auto-connect profile that the wireless service can use to connect . The interface on which connectable networks are found is identified by the InterfaceGuid member. |
| wlan_notification_acm_disconnecting 0X00000014 | The wireless service is disconnecting from a connectable network. The pData member points to a WLAN_CONNECTION_NOTIFICATION_DATA structure that identifies the network information for the connection that is disconnecting. |
| wlan_notification_acm_disconnected 0X00000015 | The wireless service has disconnected from a connectable network. The pData member points to a WLAN_CONNECTION_NOTIFICATION_DATA structure that identifies the network information for the connection that disconnected. |
| wlan_notification_acm_adhoc_network_state_change 0X00000016 | A state change has occurred for an adhoc network. The pData member points to a WLAN_ADHOC_NETWORK_STATE enumeration value that identifies the new adhoc network state. |
| wlan_notification_acm_profile_unblocked, 0X00000017 | This value is supported on Windows 8 and later. |
| wlan_notification_acm_screen_power_change 0X00000018 | The screen power has changed. The pData member points to a BOOL value that indicates the value of the screen power change. When this value is TRUE, the screen changed to on. When this value is FALSE, the screen changed to off. This value is supported on Windows 8 and later. |
| wlan_notification_acm_profile_blocked 0X00000019 | This value is supported on Windows 8 and later. |
| wlan_notification_acm_scan_list_refresh 0X0000001a | This value is supported on Windows 8 and later. |
The following values are possible when the NotificationSource member is equal to WLAN_NOTIFICATION_SOURCE_MSM.
| Value | Meaning |
|---|---|
| wlan_notification_msm_associating 0X00000001 | A wireless device is in the process of associating with an access point or a peer station. The pData member points to a WLAN_MSM_NOTIFICATION_DATA structure that contains connection-related information. |
| wlan_notification_msm_associated 0X00000002 | The wireless device has associated with an access point or a peer station. The pData member points to a WLAN_MSM_NOTIFICATION_DATA structure that contains connection-related information. |
| wlan_notification_msm_authenticating 0X00000003 | The wireless device is in the process of authenticating. The pData member of the WLAN_NOTIFICATION_DATA structure points to a WLAN_MSM_NOTIFICATION_DATA structure that contains connection-related information. |
| wlan_notification_msm_connected 0X00000004 | The wireless device is associated with an access point or a peer station, keys have been exchanged, and the wireless device is available to send data. The pData member points to a WLAN_MSM_NOTIFICATION_DATA structure that contains connection-related information. |
| wlan_notification_msm_roaming_start 0X00000005 | The wireless device is connected to an access point and has initiated roaming to another access point. The pData member points to a WLAN_MSM_NOTIFICATION_DATA structure that contains connection-related information. |
| wlan_notification_msm_roaming_end 0X00000006 | The wireless device was connected to an access point and has completed roaming to another access point. The pData member points to a WLAN_MSM_NOTIFICATION_DATA structure that contains connection-related information. |
| wlan_notification_msm_radio_state_change 0X00000007 | The radio state for an adapter has changed. Each physical layer (PHY) has its own radio state. The radio for an adapter is switched off when the radio state of every PHY is off. The pData member points to a WLAN_PHY_RADIO_STATE structure that identifies the new radio state. |
| wlan_notification_msm_signal_quality_change 0X00000008 | A signal quality change for the currently associated access point or peer station. The pData member points to a ULONG value for the WLAN_SIGNAL_QUALITY that identifies the new signal quality. |
| wlan_notification_msm_disassociating 0X00000009 | A wireless device is in the process of disassociating from an access point or a peer station. The pData member points to a WLAN_MSM_NOTIFICATION_DATA structure that contains connection-related information. |
| wlan_notification_msm_disconnected 0X0000000a | The wireless device is not associated with an access point or a peer station. The pData member points to a WLAN_MSM_NOTIFICATION_DATA structure that contains connection-related information. The wlanReasonCode member of the WLAN_MSM_NOTIFICATION_DATA structure indicates the reason for the disconnect. |
| wlan_notification_msm_peer_join 0X0000000b | A peer has joined an adhoc network. The pData member points to a WLAN_MSM_NOTIFICATION_DATA structure that contains connection-related information. |
| wlan_notification_msm_peer_leave 0X0000000c | A peer has left an adhoc network. The pData member of the WLAN_NOTIFICATION_DATA structure points to a WLAN_MSM_NOTIFICATION_DATA structure that contains connection-related information. |
| wlan_notification_msm_adapter_removal 0X0000000d | A wireless adapter has been removed from the local computer. The pData member points to a WLAN_MSM_NOTIFICATION_DATA structure that contains connection-related information. |
| wlan_notification_msm_adapter_operation_mode_change 0X0000000e | The operation mode of the wireless device has changed. The pData member points to a ULONG that identifies the new operation mode. |
The following values are possible when the NotificationSource member is equal to WLAN_NOTIFICATION_SOURCE_HNWK.
| Value | Meaning |
|---|---|
| wlan_hosted_network_state_change 0x00001000 | The wireless Hosted Network state has changed. The pData member points to a WLAN_HOSTED_NETWORK_STATE_CHANGE structure that identifies the state change. |
| wlan_hosted_network_peer_state_change 0x00001001 | The wireless Hosted Network peer state has changed. The pData member points to a WLAN_HOSTED_NETWORK_DATA_PEER_STATE_CHANGE structure that identifies the peer state change. |
| wlan_hosted_network_radio_state_change 0x00001002 | The wireless Hosted Network radio state has changed. The pData member points to a WLAN_HOSTED_NETWORK_RADIO_STATE structure that identifies the radio state change. |
InterfaceGuid
The interface on which the notification is for.
dwDataSize
The size, in bytes, of value pointed to by the pData member.
pData
A pointer to additional data provided for the notification. The type of data pointed to by the pData member is determined by the value of the NotificationCode member.
Remarks
The WlanRegisterNotification function 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 passed to the WlanRegisterNotification function. The prototype for this callback function is the WLAN_NOTIFICATION_CALLBACK. This callback function will receive notifications that have been registered 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. This client context can be a NULL pointer if that is what was passed to the WlanRegisterNotification 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 is automatically undone if the calling application closes its calling handle (by calling WlanCloseHandle with the hClientHandle parameter) used to register for notifications with the WlanRegisterNotification function or if the process ends.
An application can time out and query the current interface state instead of waiting for a notification.
If the NotificationSource member of the WLAN_NOTIFICATION_DATA structure received by the callback function is WLAN_NOTIFICATION_SOURCE_ACM, then the received notification is an auto configuration module notification. The NotificationCode member of the WLAN_NOTIFICATION_DATA structure passed to the WLAN_NOTIFICATION_CALLBACK function determines the interpretation of the pData member of WLAN_NOTIFICATION_DATA structure. For more information on these notifications, see the WLAN_NOTIFICATION_ACM enumeration reference.
The wlan_notification_acm_connection_attempt_fail notification is used only when an application tries and fails to initiate a connection using WlanConnect. This notification is sent for each failed SSID. The wlanReasonCode member of the WLAN_CONNECTION_NOTIFICATION_DATA structure included with the notification data specifies the reason the SSID failed.
If all SSIDs fail when a connection is initiated using WlanConnect, the notification wlan_notification_acm_connection_complete is sent with wlanReasonCode set to WLAN_REASON_CODE_NETWORK_NOT_AVAILABLE. If at least one SSID succeeds, then the notification is sent with wlanReasonCode set to WLAN_REASON_CODE_SUCCESS.
Unlike wlan_notification_acm_connection_attempt_fail, the wlan_notification_acm_connection_complete notification is sent for automatic connections and for connections initiated using WlanConnect. If the connection succeeds, wlanReasonCode set to WLAN_REASON_CODE_SUCCESS. Otherwise, wlanReasonCode specifies the reason for failure.
The wlan_notification_acm_filter_list_change notification is sent when there is a change in the filter list, either through group policy or a call to the WlanSetFilterList function. An application can call the WlanGetFilterList function to retrieve the new filter list.
The wlan_notification_acm_network_not_available notification is sent if the wireless service cannot find any connectable network after a scan. The interface on which no connectable network is found is identified by the InterfaceGuid member of the WLAN_NOTIFICATION_DATA structure.
The wlan_notification_acm_network_available notification is sent when all of the following conditions occur:
- The wireless service finds connectable networks after a scan
- The interface is in the disconnected state;
- There is no compatible auto-connect profile that the wireless service can use to connect.
The interface on which connectable networks are found is identified by the InterfaceGuid member of the WLAN_NOTIFICATION_DATA structure.
The wlan_notification_acm_profile_change notification is sent when there is a change in a profile or the profile list, either through group policy or by calls to Native Wifi functions. An application can call WlanGetProfileList and WlanGetProfile functions to retrieve the updated profiles. The interface on which the profile list changes is identified by the InterfaceGuid member of the WLAN_NOTIFICATION_DATA structure.
The wlan_notification_acm_profiles_exhausted notification is sent if the wireless service cannot connect to any network automatically after trying all auto-connect profiles. The notification won't be sent if there is no auto-connect profile or no connectable network. The interface is identified by identified by the InterfaceGuid member of the WLAN_NOTIFICATION_DATA structure.
If the NotificationSource member of the WLAN_NOTIFICATION_DATA structure received by the callback function is WLAN_NOTIFICATION_SOURCE_HNWK, then the received notification is a wireless Hosted Network notification supported on Windows 7 and on Windows Server 2008 R2 with the Wireless LAN Service installed. The NotificationCode member of the WLAN_NOTIFICATION_DATA structure passed to the WLAN_NOTIFICATION_CALLBACK function determines the interpretation of the pData member of WLAN_NOTIFICATION_DATA structure. For more information on these notifications, see the WLAN_HOSTED_NETWORK_NOTIFICATION_CODE enumeration reference.
If the NotificationSource member of the WLAN_NOTIFICATION_DATA structure received by the callback function is WLAN_NOTIFICATION_SOURCE_IHV, then the received notification is an indepent hardware vendor (IHV) notification. The NotificationCode member of the WLAN_NOTIFICATION_DATA structure passed to the WLAN_NOTIFICATION_CALLBACK function determines the interpretation of the pData member of WLAN_NOTIFICATION_DATA structure, which is specific to the IHV.
If the NotificationSource member of the WLAN_NOTIFICATION_DATA structure received by the callback function is WLAN_NOTIFICATION_SOURCE_MSM, then the received notification is a media specific module (MSM) notification. The NotificationCode member of the WLAN_NOTIFICATION_DATA structure passed to the WLAN_NOTIFICATION_CALLBACK function determines the interpretation of the pData member of WLAN_NOTIFICATION_DATA structure. For more information on these notifications, see the WLAN_NOTIFICATION_MSM enumeration reference.
The wlan_notification_msm_adapter_operation_mode_change notification is used when the operation mode changes. For more information about operation modes, see Native 802.11 Operation Modes. Two operation modes are supported: DOT11_OPERATION_MODE_EXTENSIBLE_STATION and DOT11_OPERATION_MODE_NETWORK_MONITOR. The operation mode constants are defined in the header file Windot11.h. When this notification is sent, pData points to the current operation mode.
The wlan_notification_msm_peer_join and wlan_notification_msm_peer_leave notifications are used only when a machine creates an ad hoc network. These notifications are not used when a machine joins an existing ad hoc network.
If the NotificationSource member of the WLAN_NOTIFICATION_DATA structure received by the callback function is WLAN_NOTIFICATION_SOURCE_ONEX, then the received notification is an 802.1X module notification. The NotificationCode member of the WLAN_NOTIFICATION_DATA structure passed to the WLAN_NOTIFICATION_CALLBACK function determines the interpretation of the pData member of WLAN_NOTIFICATION_DATA structure. For more information on these notifications, see the ONEX_NOTIFICATION_TYPE enumeration reference.
If the NotificationSource member of the WLAN_NOTIFICATION_DATA structure received by the callback function is WLAN_NOTIFICATION_SOURCE_SECURITY, then the received notification is a security notification. No notifications are currently defined for WLAN_NOTIFICATION_SOURCE_SECURITY.
The WLAN_NOTIFICATION_DATA structure is a typedef to the L2_WLAN_NOTIFICATION_DATA structure which is defined in the L2cmn.h header file which is automatically included by the Wlanapi.h header file. The L2cmn.h header file should never be used directly.
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 |
L2cmn.h (include Wlanapi.h) |
See also
WLAN_CONNECTION_NOTIFICATION_DATA
WLAN_HOSTED_NETWORK_NOTIFICATION_CODE
WLAN_HOSTED_NETWORK_DATA_PEER_STATE_CHANGE
WLAN_HOSTED_NETWORK_RADIO_STATE