WlanRegisterDeviceServiceNotification function (wlanapi.h)

Allows user mode clients with admin privileges, or User-Mode Driver Framework (UMDF) drivers, to register for unsolicited notifications corresponding to device services that they're interested in.

Syntax

DWORD WlanRegisterDeviceServiceNotification(
  HANDLE                               hClientHandle,
  const PWLAN_DEVICE_SERVICE_GUID_LIST pDevSvcGuidList
);

Parameters

hClientHandle

Type: HANDLE

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

pDevSvcGuidList

Type: CONST PWLAN_DEVICE_SERVICE_GUID_LIST

An optional pointer to a constant WLAN_DEVICE_SERVICE_GUID_LIST structure representing the device service GUIDs for which you're interested in receiving notifications. The dwIndex member of the structure must have a value less than the value of its dwNumberOfItems member; otherwise, an access violation may occur. Every time you call this API, the previous device services list is replaced by the new one.

To unregister, set pDevSvcGuidList to nullptr, or pass a pointer to a WLAN_DEVICE_SERVICE_GUID_LIST structure that has the dwNumberOfItems member set to 0.

Return value

Type: HRESULT

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails with ERROR_ACCESS_DENIED, then the caller doesn't have sufficient permissions to perform this operation. The caller needs to either have admin privilege, or needs to be a UMDF driver.

Remarks

The WlanRegisterDeviceServiceNotification function is an extension to existing native Wi-Fi APIs for WLAN device services.

A client application calls this function to register and unregister notifications for device services that it is interested in.

Any registration to receive notifications for device services 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.

In order to receive these notifications, a client needs to call this function with a valid pDevSvcGuidList parameter, and must also call the WlanRegisterNotification function with a dwNotifSource argument of WLAN_NOTIFICATION_SOURCE_DEVICE_SERVICE (which is defined in wlanapi.h). The registration to receive notifications for device services is in effect until the application closes the client handle (by calling WlanCloseHandle with the hClientHandle parameter), or the process ends, or WlanRegisterDeviceServiceNotification is called with a pDevSvcGuidList argument of nullptr, or else has dwNumberOfItems set to 0.

When the operating system (OS) receives a device service notification from an independent hardware vendor (IHV) driver, and a client has registered for these notifications using WlanRegisterDeviceServiceNotification, the client will receive them via the WLAN_NOTIFICATION_CALLBACK that it had registered through its call to WlanRegisterNotification. This callback will be called for every notification that the client has received (with a separate buffer for every notification).

The NotificationSource member of the WLAN_NOTIFICATION_DATA structure received by the callback function (that is, the data member) will be set to WLAN_NOTIFICATION_SOURCE_DEVICE_SERVICE. The data blob, the device service GUID, and the opcode associated with this notification will be present in the pData member of the WLAN_NOTIFICATION_DATA, which will point to a structure of type WLAN_DEVICE_SERVICE_NOTIFICATION_DATA.

Note

The WLAN service, or the OS, will not check to see whether the device service GUIDs that the client registers for are actually supported by the IHV driver. It is up to the client to query for supported device services using WlanGetSupportedDeviceServices API if they need to.

Requirements

Requirement	Value
Minimum supported client	Windows 10 Build 20348
Minimum supported server	Windows 10 Build 20348
Header	wlanapi.h