WlanQueryInterface function (wlanapi.h)
Note
Some information relates to pre-released product, which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Important
This API will be affected by upcoming changes to operating system behavior, planned for fall 2024. For more info, see Changes to API behavior for Wi-Fi access and location.
The WlanQueryInterface function queries various parameters of a specified interface.
Syntax
DWORD WlanQueryInterface(
[in] HANDLE hClientHandle,
[in] const GUID *pInterfaceGuid,
[in] WLAN_INTF_OPCODE OpCode,
PVOID pReserved,
[out] PDWORD pdwDataSize,
[out] PVOID *ppData,
[out, optional] PWLAN_OPCODE_VALUE_TYPE pWlanOpcodeValueType
);
Parameters
[in] hClientHandle
The client's session handle, obtained by a previous call to the WlanOpenHandle function.
[in] pInterfaceGuid
The GUID of the interface to be queried.
[in] OpCode
A WLAN_INTF_OPCODE value that specifies the parameter to be queried. The following table lists the valid constants along with the data type of the parameter in ppData.
| WLAN_INTF_OPCODE | ppData data type |
|---|---|
| wlan_intf_opcode_autoconf_enabled | BOOL |
| wlan_intf_opcode_background_scan_enabled | BOOL |
| wlan_intf_opcode_bss_type | DOT11_BSS_TYPE |
| wlan_intf_opcode_certified_safe_mode | BOOL |
| wlan_intf_opcode_channel_number | ULONG |
| wlan_intf_opcode_current_connection | WLAN_CONNECTION_ATTRIBUTES |
| wlan_intf_opcode_current_operation_mode | ULONG |
| wlan_intf_opcode_hosted_network_capable | BOOL |
| wlan_intf_opcode_interface_state | WLAN_INTERFACE_STATE |
| wlan_intf_opcode_management_frame_protection_capable | BOOL |
| wlan_intf_opcode_media_streaming_mode | BOOL |
| wlan_intf_opcode_qos_info | WLAN_QOS_INFO |
| wlan_intf_opcode_radio_state | WLAN_RADIO_STATE |
| wlan_intf_opcode_realtime_connection_quality | WLAN_REALTIME_CONNECTION_QUALITY |
| wlan_intf_opcode_rssi | LONG |
| wlan_intf_opcode_secondary_sta_interfaces | WLAN_INTERFACE_INFO_LIST |
| wlan_intf_opcode_secondary_sta_synchronized_connections | BOOL |
| wlan_intf_opcode_statistics | WLAN_STATISTICS |
| wlan_intf_opcode_supported_adhoc_auth_cipher_pairs | WLAN_AUTH_CIPHER_PAIR_LIST |
| wlan_intf_opcode_supported_country_or_region_string_list | WLAN_COUNTRY_OR_REGION_STRING_LIST |
| wlan_intf_opcode_supported_infrastructure_auth_cipher_pairs | WLAN_AUTH_CIPHER_PAIR_LIST |
| wlan_intf_opcode_supported_safe_mode | BOOL |
Windows XP with SP3 and Wireless LAN API for Windows XP with SP2: Only the wlan_intf_opcode_autoconf_enabled, wlan_intf_opcode_bss_type, wlan_intf_opcode_interface_state, and wlan_intf_opcode_current_connection constants are valid.
pReserved
Reserved for future use. Must be set to NULL.
[out] pdwDataSize
The size of the ppData parameter, in bytes.
[out] ppData
Pointer to the memory location that contains the queried value of the parameter specified by the OpCode parameter.
Note If OpCode is set to wlan_intf_opcode_autoconf_enabled, wlan_intf_opcode_background_scan_enabled, or wlan_intf_opcode_media_streaming_mode, then the pointer referenced by ppData may point to an integer value. If the pointer referenced by ppData points to 0, then the integer value should be converted to the boolean value FALSE. If the pointer referenced by ppData points to a nonzero integer, then the integer value should be converted to the boolean value TRUE.
[out, optional] pWlanOpcodeValueType
If passed a non-NULL value, points to a WLAN_OPCODE_VALUE_TYPE value that specifies the type of opcode returned. This parameter may be NULL.
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.
Remarks
The caller is responsible for using WlanFreeMemory to free the memory allocated for ppData.
When OpCode is set to wlan_intf_opcode_current_operation_mode, WlanQueryInterface queries the current operation mode of the wireless interface. 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. ppData will point to one of these two values.
Examples
The following example enumerates the wireless LAN interfaces on the local computer, queries each interface for the WLAN_CONNECTION_ATTRIBUTES on the interface, and prints values from the retrieved WLAN_CONNECTION_ATTRIBUTES structure.
For another example using the WlanQueryInterface function, see the WLAN_RADIO_STATE structure.
Note This example will fail to load on Windows Server 2008 and Windows Server 2008 R2 if the Wireless LAN Service is not installed and started.
#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <wlanapi.h>
#include <Windot11.h> // for DOT11_SSID struct
#include <objbase.h>
#include <wtypes.h>
//#include <wchar.h>
#include <stdio.h>
#include <stdlib.h>
// Need to link with Wlanapi.lib and Ole32.lib
#pragma comment(lib, "wlanapi.lib")
#pragma comment(lib, "ole32.lib")
int wmain()
{
// Declare and initialize variables.
HANDLE hClient = NULL;
DWORD dwMaxClient = 2; //
DWORD dwCurVersion = 0;
DWORD dwResult = 0;
DWORD dwRetVal = 0;
int iRet = 0;
WCHAR GuidString[39] = { 0 };
unsigned int i, k;
// variables used for WlanEnumInterfaces
PWLAN_INTERFACE_INFO_LIST pIfList = NULL;
PWLAN_INTERFACE_INFO pIfInfo = NULL;
// variables used for WlanQueryInterfaces for opcode = wlan_intf_opcode_current_connection
PWLAN_CONNECTION_ATTRIBUTES pConnectInfo = NULL;
DWORD connectInfoSize = sizeof(WLAN_CONNECTION_ATTRIBUTES);
WLAN_OPCODE_VALUE_TYPE opCode = wlan_opcode_value_type_invalid;
dwResult = WlanOpenHandle(dwMaxClient, NULL, &dwCurVersion, &hClient);
if (dwResult != ERROR_SUCCESS) {
wprintf(L"WlanOpenHandle failed with error: %u\n", dwResult);
return 1;
// You can use FormatMessage here to find out why the function failed
}
dwResult = WlanEnumInterfaces(hClient, NULL, &pIfList);
if (dwResult != ERROR_SUCCESS) {
wprintf(L"WlanEnumInterfaces failed with error: %u\n", dwResult);
return 1;
// You can use FormatMessage here to find out why the function failed
} else {
wprintf(L"Num Entries: %lu\n", pIfList->dwNumberOfItems);
wprintf(L"Current Index: %lu\n", pIfList->dwIndex);
for (i = 0; i < (int) pIfList->dwNumberOfItems; i++) {
pIfInfo = (WLAN_INTERFACE_INFO *) & pIfList->InterfaceInfo[i];
wprintf(L" Interface Index[%u]:\t %lu\n", i, i);
iRet =
StringFromGUID2(pIfInfo->InterfaceGuid, (LPOLESTR) & GuidString,
sizeof (GuidString) / sizeof (*GuidString));
// For c rather than C++ source code, the above line needs to be
// iRet = StringFromGUID2(&pIfInfo->InterfaceGuid, (LPOLESTR) &GuidString,
// sizeof(GuidString)/sizeof(*GuidString));
if (iRet == 0)
wprintf(L"StringFromGUID2 failed\n");
else {
wprintf(L" InterfaceGUID[%d]:\t %ws\n", i, GuidString);
}
wprintf(L" Interface Description[%d]: %ws", i, pIfInfo->strInterfaceDescription);
wprintf(L"\n");
wprintf(L" Interface State[%d]:\t ", i);
switch (pIfInfo->isState) {
case wlan_interface_state_not_ready:
wprintf(L"Not ready\n");
break;
case wlan_interface_state_connected:
wprintf(L"Connected\n");
break;
case wlan_interface_state_ad_hoc_network_formed:
wprintf(L"First node in a ad hoc network\n");
break;
case wlan_interface_state_disconnecting:
wprintf(L"Disconnecting\n");
break;
case wlan_interface_state_disconnected:
wprintf(L"Not connected\n");
break;
case wlan_interface_state_associating:
wprintf(L"Attempting to associate with a network\n");
break;
case wlan_interface_state_discovering:
wprintf(L"Auto configuration is discovering settings for the network\n");
break;
case wlan_interface_state_authenticating:
wprintf(L"In process of authenticating\n");
break;
default:
wprintf(L"Unknown state %ld\n", pIfInfo->isState);
break;
}
wprintf(L"\n");
// If interface state is connected, call WlanQueryInterface
// to get current connection attributes
if (pIfInfo->isState == wlan_interface_state_connected) {
dwResult = WlanQueryInterface(hClient,
&pIfInfo->InterfaceGuid,
wlan_intf_opcode_current_connection,
NULL,
&connectInfoSize,
(PVOID *) &pConnectInfo,
&opCode);
if (dwResult != ERROR_SUCCESS) {
wprintf(L"WlanQueryInterface failed with error: %u\n", dwResult);
dwRetVal = 1;
// You can use FormatMessage to find out why the function failed
} else {
wprintf(L" WLAN_CONNECTION_ATTRIBUTES for this interface\n");
wprintf(L" Interface State:\t ");
switch (pConnectInfo->isState) {
case wlan_interface_state_not_ready:
wprintf(L"Not ready\n");
break;
case wlan_interface_state_connected:
wprintf(L"Connected\n");
break;
case wlan_interface_state_ad_hoc_network_formed:
wprintf(L"First node in a ad hoc network\n");
break;
case wlan_interface_state_disconnecting:
wprintf(L"Disconnecting\n");
break;
case wlan_interface_state_disconnected:
wprintf(L"Not connected\n");
break;
case wlan_interface_state_associating:
wprintf(L"Attempting to associate with a network\n");
break;
case wlan_interface_state_discovering:
wprintf
(L"Auto configuration is discovering settings for the network\n");
break;
case wlan_interface_state_authenticating:
wprintf(L"In process of authenticating\n");
break;
default:
wprintf(L"Unknown state %ld\n", pIfInfo->isState);
break;
}
wprintf(L" Connection Mode:\t ");
switch (pConnectInfo->wlanConnectionMode) {
case wlan_connection_mode_profile:
wprintf(L"A profile is used to make the connection\n");
break;
case wlan_connection_mode_temporary_profile:
wprintf(L"A temporary profile is used to make the connection\n");
break;
case wlan_connection_mode_discovery_secure:
wprintf(L"Secure discovery is used to make the connection\n");
break;
case wlan_connection_mode_discovery_unsecure:
wprintf(L"Unsecure discovery is used to make the connection\n");
break;
case wlan_connection_mode_auto:
wprintf
(L"connection initiated by wireless service automatically using a persistent profile\n");
break;
case wlan_connection_mode_invalid:
wprintf(L"Invalid connection mode\n");
break;
default:
wprintf(L"Unknown connection mode %ld\n",
pConnectInfo->wlanConnectionMode);
break;
}
wprintf(L" Profile name used:\t %ws\n", pConnectInfo->strProfileName);
wprintf(L" Association Attributes for this connection\n");
wprintf(L" SSID:\t\t ");
if (pConnectInfo->wlanAssociationAttributes.dot11Ssid.uSSIDLength == 0)
wprintf(L"\n");
else {
for (k = 0;
k < pConnectInfo->wlanAssociationAttributes.dot11Ssid.uSSIDLength;
k++) {
wprintf(L"%c",
(int) pConnectInfo->wlanAssociationAttributes.dot11Ssid.
ucSSID[k]);
}
wprintf(L"\n");
}
wprintf(L" BSS Network type:\t ");
switch (pConnectInfo->wlanAssociationAttributes.dot11BssType) {
case dot11_BSS_type_infrastructure:
wprintf(L"Infrastructure\n");
break;
case dot11_BSS_type_independent:
wprintf(L"Infrastructure\n");
break;
default:
wprintf(L"Other = %lu\n",
pConnectInfo->wlanAssociationAttributes.dot11BssType);
break;
}
wprintf(L" MAC address:\t ");
for (k = 0; k < sizeof (pConnectInfo->wlanAssociationAttributes.dot11Bssid);
k++) {
if (k == 5)
wprintf(L"%.2X\n",
pConnectInfo->wlanAssociationAttributes.dot11Bssid[k]);
else
wprintf(L"%.2X-",
pConnectInfo->wlanAssociationAttributes.dot11Bssid[k]);
}
wprintf(L" PHY network type:\t ");
switch (pConnectInfo->wlanAssociationAttributes.dot11PhyType) {
case dot11_phy_type_fhss:
wprintf(L"Frequency-hopping spread-spectrum (FHSS)\n");
break;
case dot11_phy_type_dsss:
wprintf(L"Direct sequence spread spectrum (DSSS)\n");
break;
case dot11_phy_type_irbaseband:
wprintf(L"Infrared (IR) baseband\n");
break;
case dot11_phy_type_ofdm:
wprintf(L"Orthogonal frequency division multiplexing (OFDM)\n");
break;
case dot11_phy_type_hrdsss:
wprintf(L"High-rate DSSS (HRDSSS) = \n");
break;
case dot11_phy_type_erp:
wprintf(L"Extended rate PHY type\n");
break;
case dot11_phy_type_ht:
wprintf(L"802.11n PHY type\n");
break;
default:
wprintf(L"Unknown = %lu\n",
pConnectInfo->wlanAssociationAttributes.dot11PhyType);
break;
}
wprintf(L" PHY index:\t\t %u\n",
pConnectInfo->wlanAssociationAttributes.uDot11PhyIndex);
wprintf(L" Signal Quality:\t %d\n",
pConnectInfo->wlanAssociationAttributes.wlanSignalQuality);
wprintf(L" Receiving Rate:\t %ld\n",
pConnectInfo->wlanAssociationAttributes.ulRxRate);
wprintf(L" Transmission Rate:\t %ld\n",
pConnectInfo->wlanAssociationAttributes.ulTxRate);
wprintf(L"\n");
wprintf(L" Security Attributes for this connection\n");
wprintf(L" Security enabled:\t ");
if (pConnectInfo->wlanSecurityAttributes.bSecurityEnabled == 0)
wprintf(L"No\n");
else
wprintf(L"Yes\n");
wprintf(L" 802.1X enabled:\t ");
if (pConnectInfo->wlanSecurityAttributes.bOneXEnabled == 0)
wprintf(L"No\n");
else
wprintf(L"Yes\n");
wprintf(L" Authentication Algorithm: ");
switch (pConnectInfo->wlanSecurityAttributes.dot11AuthAlgorithm) {
case DOT11_AUTH_ALGO_80211_OPEN:
wprintf(L"802.11 Open\n");
break;
case DOT11_AUTH_ALGO_80211_SHARED_KEY:
wprintf(L"802.11 Shared\n");
break;
case DOT11_AUTH_ALGO_WPA:
wprintf(L"WPA\n");
break;
case DOT11_AUTH_ALGO_WPA_PSK:
wprintf(L"WPA-PSK\n");
break;
case DOT11_AUTH_ALGO_WPA_NONE:
wprintf(L"WPA-None\n");
break;
case DOT11_AUTH_ALGO_RSNA:
wprintf(L"RSNA\n");
break;
case DOT11_AUTH_ALGO_RSNA_PSK:
wprintf(L"RSNA with PSK\n");
break;
default:
wprintf(L"Other (%lu)\n", pConnectInfo->wlanSecurityAttributes.dot11AuthAlgorithm);
break;
}
wprintf(L" Cipher Algorithm:\t ");
switch (pConnectInfo->wlanSecurityAttributes.dot11CipherAlgorithm) {
case DOT11_CIPHER_ALGO_NONE:
wprintf(L"None\n");
break;
case DOT11_CIPHER_ALGO_WEP40:
wprintf(L"WEP-40\n");
break;
case DOT11_CIPHER_ALGO_TKIP:
wprintf(L"TKIP\n");
break;
case DOT11_CIPHER_ALGO_CCMP:
wprintf(L"CCMP\n");
break;
case DOT11_CIPHER_ALGO_WEP104:
wprintf(L"WEP-104\n");
break;
case DOT11_CIPHER_ALGO_WEP:
wprintf(L"WEP\n");
break;
default:
wprintf(L"Other (0x%x)\n", pConnectInfo->wlanSecurityAttributes.dot11CipherAlgorithm);
break;
}
wprintf(L"\n");
}
}
}
}
if (pConnectInfo != NULL) {
WlanFreeMemory(pConnectInfo);
pConnectInfo = NULL;
}
if (pIfList != NULL) {
WlanFreeMemory(pIfList);
pIfList = NULL;
}
return dwRetVal;
}
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista, Windows XP with SP3 [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | wlanapi.h (include Wlanapi.h) |
| Library | Wlanapi.lib |
| DLL | Wlanapi.dll |
| Redistributable | Wireless LAN API for Windows XP with SP2 |