WlanGetAvailableNetworkList 函式 (wlanapi.h)
注意
針對發行前產品的部分相關資訊，在產品正式發行時可能會有大幅修改。 針對此處提供的資訊，Microsoft 不做任何明示或默許的擔保。
重要
此 API 將受到即將變更的操作系統行為所影響，其計劃為 2024 年 2024 年。 如需詳細資訊，請參閱 Wi-Fi 存取和位置的 API 行為變更。
WlanGetAvailableNetworkList 函式會擷取無線 LAN 介面上可用網路的清單。
語法
DWORD WlanGetAvailableNetworkList(
[in] HANDLE hClientHandle,
[in] const GUID *pInterfaceGuid,
[in] DWORD dwFlags,
PVOID pReserved,
[out] PWLAN_AVAILABLE_NETWORK_LIST *ppAvailableNetworkList
);
參數
[in] hClientHandle
用戶端的會話句柄，由先前呼叫 WlanOpenHandle 函式取得。
[in] pInterfaceGuid
要查詢之無線 LAN 介面之 GUID 的指標。
您可以使用 WlanEnumInterfaces 函式來判斷本機電腦上啟用的每個無線 LAN 介面 GUID。
[in] dwFlags
一組旗標，控制清單中傳回的網路類型。 此參數可以是這些可能值的組合。
pReserved
保留供未來使用。 此參數必須設定為 NULL。
[out] ppAvailableNetworkList
指標的記憶體指標，用於接收 WLAN_AVAILABLE_NETWORK_LIST 結構中可見網路的傳回清單。
如果呼叫成功，則 WlanGetAvailableNetworkList 函式會配置所傳回WLAN_AVAILABLE_NETWORK_LIST緩衝區。
傳回值
如果函式成功，傳回值會ERROR_SUCCESS。
如果函式失敗，傳回值可能是下列其中一個傳回碼。
| 傳回碼 | Description |
|---|---|
|
參數不正確。 如果 hClientHandle、 pInterfaceGuid 或 ppAvailableNetworkList 參數為 NULL，就會傳回 此錯誤。 如果 pReserved 不是 NULL，則會傳回 此錯誤。 如果 dwFlags 參數值設定為無效或 hClientHandle 參數無效的值，也會傳回此錯誤。 |
|
句柄數據表中找不到句柄 hClientHandle 。 |
|
與介面相關聯的無線電已關閉。 當無線電關閉時，沒有可用的網路。 |
|
各種錯誤碼。 |
|
沒有足夠的記憶體可用來處理此要求，並配置查詢結果的記憶體。 |
備註
WlanGetAvailableNetworkList 函式會在函式成功時，為 ppAvailableNetworkList 參數所指向緩衝區中傳回的可用網路清單配置記憶體。 不再需要緩衝區之後呼叫 WlanFreeMemory 函式，即可釋放 ppAvailableNetworkList 參數所指向之緩衝區的記憶體。
Windows XP 的無線 LAN API 有一個 Hotfix，可協助改善呼叫 WlanFreeMemory 和 WlanGetAvailableNetworkList 多次的應用程式效能。
範例
下列範例會列舉本機計算機上的無線 LAN 介面、擷取每個無線 LAN 介面上的可用網路清單，並從包含WLAN_AVAILABLE_NETWORK專案的擷取WLAN_AVAILABLE_NETWORK_LIST印表值。
注意 如果未安裝並啟動無線 LAN 服務，此範例將無法載入 Windows Server 2008 和 Windows Server 2008 R2。
#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <wlanapi.h>
#include <objbase.h>
#include <wtypes.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, j, k;
/* variables used for WlanEnumInterfaces */
PWLAN_INTERFACE_INFO_LIST pIfList = NULL;
PWLAN_INTERFACE_INFO pIfInfo = NULL;
PWLAN_AVAILABLE_NETWORK_LIST pBssList = NULL;
PWLAN_AVAILABLE_NETWORK pBssEntry = NULL;
int iRSSI = 0;
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]: %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");
dwResult = WlanGetAvailableNetworkList(hClient,
&pIfInfo->InterfaceGuid,
0,
NULL,
&pBssList);
if (dwResult != ERROR_SUCCESS) {
wprintf(L"WlanGetAvailableNetworkList failed with error: %u\n",
dwResult);
dwRetVal = 1;
// You can use FormatMessage to find out why the function failed
} else {
wprintf(L"WLAN_AVAILABLE_NETWORK_LIST for this interface\n");
wprintf(L" Num Entries: %lu\n\n", pBssList->dwNumberOfItems);
for (j = 0; j < pBssList->dwNumberOfItems; j++) {
pBssEntry =
(WLAN_AVAILABLE_NETWORK *) & pBssList->Network[j];
wprintf(L" Profile Name[%u]: %ws\n", j, pBssEntry->strProfileName);
wprintf(L" SSID[%u]:\t\t ", j);
if (pBssEntry->dot11Ssid.uSSIDLength == 0)
wprintf(L"\n");
else {
for (k = 0; k < pBssEntry->dot11Ssid.uSSIDLength; k++) {
wprintf(L"%c", (int) pBssEntry->dot11Ssid.ucSSID[k]);
}
wprintf(L"\n");
}
wprintf(L" BSS Network type[%u]:\t ", j);
switch (pBssEntry->dot11BssType) {
case dot11_BSS_type_infrastructure :
wprintf(L"Infrastructure (%u)\n", pBssEntry->dot11BssType);
break;
case dot11_BSS_type_independent:
wprintf(L"Infrastructure (%u)\n", pBssEntry->dot11BssType);
break;
default:
wprintf(L"Other (%lu)\n", pBssEntry->dot11BssType);
break;
}
wprintf(L" Number of BSSIDs[%u]:\t %u\n", j, pBssEntry->uNumberOfBssids);
wprintf(L" Connectable[%u]:\t ", j);
if (pBssEntry->bNetworkConnectable)
wprintf(L"Yes\n");
else {
wprintf(L"No\n");
wprintf(L" Not connectable WLAN_REASON_CODE value[%u]:\t %u\n", j,
pBssEntry->wlanNotConnectableReason);
}
wprintf(L" Number of PHY types supported[%u]:\t %u\n", j, pBssEntry->uNumberOfPhyTypes);
if (pBssEntry->wlanSignalQuality == 0)
iRSSI = -100;
else if (pBssEntry->wlanSignalQuality == 100)
iRSSI = -50;
else
iRSSI = -100 + (pBssEntry->wlanSignalQuality/2);
wprintf(L" Signal Quality[%u]:\t %u (RSSI: %i dBm)\n", j,
pBssEntry->wlanSignalQuality, iRSSI);
wprintf(L" Security Enabled[%u]:\t ", j);
if (pBssEntry->bSecurityEnabled)
wprintf(L"Yes\n");
else
wprintf(L"No\n");
wprintf(L" Default AuthAlgorithm[%u]: ", j);
switch (pBssEntry->dot11DefaultAuthAlgorithm) {
case DOT11_AUTH_ALGO_80211_OPEN:
wprintf(L"802.11 Open (%u)\n", pBssEntry->dot11DefaultAuthAlgorithm);
break;
case DOT11_AUTH_ALGO_80211_SHARED_KEY:
wprintf(L"802.11 Shared (%u)\n", pBssEntry->dot11DefaultAuthAlgorithm);
break;
case DOT11_AUTH_ALGO_WPA:
wprintf(L"WPA (%u)\n", pBssEntry->dot11DefaultAuthAlgorithm);
break;
case DOT11_AUTH_ALGO_WPA_PSK:
wprintf(L"WPA-PSK (%u)\n", pBssEntry->dot11DefaultAuthAlgorithm);
break;
case DOT11_AUTH_ALGO_WPA_NONE:
wprintf(L"WPA-None (%u)\n", pBssEntry->dot11DefaultAuthAlgorithm);
break;
case DOT11_AUTH_ALGO_RSNA:
wprintf(L"RSNA (%u)\n", pBssEntry->dot11DefaultAuthAlgorithm);
break;
case DOT11_AUTH_ALGO_RSNA_PSK:
wprintf(L"RSNA with PSK(%u)\n", pBssEntry->dot11DefaultAuthAlgorithm);
break;
default:
wprintf(L"Other (%lu)\n", pBssEntry->dot11DefaultAuthAlgorithm);
break;
}
wprintf(L" Default CipherAlgorithm[%u]: ", j);
switch (pBssEntry->dot11DefaultCipherAlgorithm) {
case DOT11_CIPHER_ALGO_NONE:
wprintf(L"None (0x%x)\n", pBssEntry->dot11DefaultCipherAlgorithm);
break;
case DOT11_CIPHER_ALGO_WEP40:
wprintf(L"WEP-40 (0x%x)\n", pBssEntry->dot11DefaultCipherAlgorithm);
break;
case DOT11_CIPHER_ALGO_TKIP:
wprintf(L"TKIP (0x%x)\n", pBssEntry->dot11DefaultCipherAlgorithm);
break;
case DOT11_CIPHER_ALGO_CCMP:
wprintf(L"CCMP (0x%x)\n", pBssEntry->dot11DefaultCipherAlgorithm);
break;
case DOT11_CIPHER_ALGO_WEP104:
wprintf(L"WEP-104 (0x%x)\n", pBssEntry->dot11DefaultCipherAlgorithm);
break;
case DOT11_CIPHER_ALGO_WEP:
wprintf(L"WEP (0x%x)\n", pBssEntry->dot11DefaultCipherAlgorithm);
break;
default:
wprintf(L"Other (0x%x)\n", pBssEntry->dot11DefaultCipherAlgorithm);
break;
}
wprintf(L" Flags[%u]:\t 0x%x", j, pBssEntry->dwFlags);
if (pBssEntry->dwFlags) {
if (pBssEntry->dwFlags & WLAN_AVAILABLE_NETWORK_CONNECTED)
wprintf(L" - Currently connected");
if (pBssEntry->dwFlags & WLAN_AVAILABLE_NETWORK_HAS_PROFILE)
wprintf(L" - Has profile");
}
wprintf(L"\n");
wprintf(L"\n");
}
}
}
}
if (pBssList != NULL) {
WlanFreeMemory(pBssList);
pBssList = NULL;
}
if (pIfList != NULL) {
WlanFreeMemory(pIfList);
pIfList = NULL;
}
return dwRetVal;
}
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows Vista、Windows XP SP3 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2008 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | wlanapi.h (包含 Wlanapi.h) |
| 程式庫 | Wlanapi.lib |
| Dll | Wlanapi.dll |
| 可轉散發套件 | Windows XP 搭配 SP2 的無線 LAN API |