GetAndMonitorWirelessDevices (Compact 2013)
3/26/2014
This function retrieves the linked list of the wireless devices in the system and sets up a monitoring thread to notify the caller about the subsequent addition and removal of wireless devices.
Syntax
HRESULT GetAndMonitorWirelessDevices(
RDD **pDevices,
DWORD dwFlags
WRLSNOTIFY *pNotify
HANDLE *rghThread
);
Parameters
dwFlags
[in] Specifies the which devices to retrieve and whether or not to retrieve their desired state also. The following table shows the possible flag values.Flag
Description
WIRELESS_GET_DESIRED (1)
This flag returns the desired state of the device in the dwDesired member of the RDD structure. This is the user's preferred state when wireless signals are on. For example, if the user has set the phone checkbox in the Power section of Control Panel, but turned all wireless devices off, this member would be 1, but the actual state, dwState, would be 0. If you are only interested in the current state of devices, do not pass this flag. This will not result in a meaningful value in the dwDesired member.
WIRELESS_NO_POWER_MAN (2)
This flag causes GetAndMonitorWirelessDevices to exclude any power managed wireless LAN adapters from the returned list.
WIRELESS_NO_PHONE (4)
Passing this flag causes GetAndMonitorWirelessDevices to exclude any phone radios from the returned list of devices.
- pNotify
[in] Pointer to a WRLSNOTIFY structure that stores a pointer to a callback function and any user data you want passed back to the callback function.
- pDevices
[out] On return, this parameter is filled with a linked list of the currently existing radio devices or NULL if none exist.
- rghThread
[out] Pointer to a handle to receive the notification thread's handle. If this parameter is NULL, the function runs synchronously and returns. It is equivalent to calling the GetWirelessDevices function. When the calling application finishes monitoring, it should shut down this thread by signaling WRLS_TERMINATE_EVENT.
Return Value
The following table shows the return values for this function.
Value |
Description |
|---|---|
S_OK |
Successfully retrieved the list of wireless devices. |
E_FAIL |
Unspecified failure. |
E_OUTOFMEMORY |
Insufficient memory. |
Other error messages maybe returned depending on the device.
Remarks
The pfnCallback member of WRLSNOTIFY points to the callback function that will be called when devices are added or removed. Because wireless devices can be added and removed at any time, some applications might need to monitor these devices in the system rather than just take a snapshot of the current state. For example, Wireless tab in the Control Panel monitors the state of the wireless devices so it can update itself dynamically as devices are added and removed. To do this, implement a callback function to receive the notifications as defined by PFN_WRLSPOWERSTATUSCHANGE, then call the GetAndMonitorWirelessDevices function.
Requirements
Header |
wrlspwr.h |
Library |
ossvcs.lib |