WlanGetProfile 函式 (wlanapi.h)
WlanGetProfile 函式會擷取指定無線設定檔的所有資訊。
語法
DWORD WlanGetProfile(
[in] HANDLE hClientHandle,
[in] const GUID *pInterfaceGuid,
[in] LPCWSTR strProfileName,
[in] PVOID pReserved,
[out] LPWSTR *pstrProfileXml,
[in, out, optional] DWORD *pdwFlags,
[out, optional] DWORD *pdwGrantedAccess
);
參數
[in] hClientHandle
用戶端的會話控制碼，由先前呼叫 WlanOpenHandle 函式取得。
[in] pInterfaceGuid
無線介面的 GUID。
您可以使用 WlanEnumInterfaces 函式來擷取本機電腦上無線介面的 GUID 清單。
[in] strProfileName
設定檔的名稱。 設定檔名稱會區分大小寫。 此字串必須以 Null 終止。 設定檔名稱的最大長度為 255 個字元。 這表示此字串的最大長度，包括 Null 結束字元為 256 個字元。
Windows XP with SP3 和 Wireless LAN API for Windows XP with SP2： 設定檔的名稱會自動衍生自網路的 SSID。 針對基礎結構網路設定檔，設定檔的名稱是網路的 SSID。 針對臨機操作網路設定檔，設定檔的名稱是臨機操作網路的 SSID，後面接著 -adhoc 。
[in] pReserved
保留供未來使用。 必須設定為 Null。
[out] pstrProfileXml
字串，表示查詢的設定檔的 XML 表示。 沒有預先定義的字串長度上限。
[in, out, optional] pdwFlags
在輸入時，用來提供要求其他資訊的位址位置指標。 如果輸入時此參數為 Null ，則不會傳回設定檔旗標的相關資訊。 在輸出中，用來接收設定檔旗標之位址位置的指標。
Windows XP with SP3 和 Wireless LAN API for Windows XP with SP2： 不支援個別使用者設定檔。 將此參數設定為 Null。
pdwFlags參數可以指向包含下列值的位址位置：
| 值 | 意義 |
|---|---|
|
在輸入時，此旗標表示呼叫端想要從無線設定檔擷取純文字金鑰。 如果呼叫執行緒具有必要的許可權，WlanGetProfile函式會傳回pstrProfileXml參數所指向緩衝區中設定檔keyMaterial元素中的純文字索引鍵。
若要讓WlanGetProfile呼叫傳回純文字索引鍵，必須在呼叫執行緒上設定來自WLAN_SECURABLE_OBJECT列舉類型的wlan_secure_get_plaiNtext_key許可權。 DACL 也必須包含 ACE，授與呼叫執行緒之存取權杖 的WLAN_READ_ACCESS 許可權。 根據預設，只允許擷取純文字金鑰的許可權給本機電腦上的 Administrators 群組成員。 如果呼叫執行緒缺少必要的許可權，WlanGetProfile函式會傳回pstrProfileXml參數所指向緩衝區中設定檔keyMaterial元素中的加密金鑰。 如果呼叫執行緒缺少必要的許可權，則不會傳回任何錯誤。 Windows 7： 此在輸入上傳遞的旗標是 Windows 7 和更新版本上新增之原生無線 API 的延伸模組。 pdwFlags參數是 Windows 7 和更新版本上的__inout_opt參數。 |
|
在 WlanGetProfile呼叫成功時輸出時，此旗標表示此設定檔是由群組原則所建立。 群組原則設定檔是唯讀的。 無法變更設定檔的內容和喜好設定順序。 |
|
在 WlanGetProfile 呼叫成功時輸出時，此旗標表示設定檔是呼叫執行緒所在內容之特定使用者的使用者設定檔。 如果未設定，則此設定檔是所有使用者設定檔。 |
[out, optional] pdwGrantedAccess
所有使用者設定檔的存取遮罩。
| 值 | 意義 |
|---|---|
|
使用者可以檢視設定檔的內容。 |
|
使用者具有讀取權限，而且使用者也可以使用設定檔來連線和中斷網路連線。 如果使用者有WLAN_EXECUTE_ACCESS，則使用者也會有WLAN_READ_ACCESS。 |
|
使用者具有執行存取權，而且使用者也可以修改設定檔的內容或刪除設定檔。 如果使用者有WLAN_WRITE_ACCESS，則使用者也有WLAN_EXECUTE_ACCESS和WLAN_READ_ACCESS。 |
傳回值
如果函式成功，傳回值會ERROR_SUCCESS。
如果函式失敗，傳回值可能是下列其中一個傳回碼。
| 傳回碼 | Description |
|---|---|
|
呼叫端沒有足夠的許可權。 如果 pstrProfileXml 參數指定了所有使用者設定檔，但呼叫端在設定檔上沒有讀取權限，就會傳回此錯誤。 |
|
控制碼無效。 如果在控制碼資料表中找不到 hClientHandle 參數中指定的控制碼，就會傳回此錯誤。 |
|
參數不正確。 如果發生下列任一狀況，就會傳回此錯誤：
|
|
沒有足夠的儲存體可用來處理此命令。 如果系統無法為設定檔配置記憶體，就會傳回此錯誤。 |
|
找不到 strProfileName 所指定的設定檔。 |
|
各種 RPC 和其他錯誤碼。 使用 FormatMessage 取得傳回錯誤的訊息字串。 |
備註
如果 WlanGetProfile 函式成功，則會在 pstrProfileXml 參數指向的緩衝區中傳回無線設定檔。 緩衝區包含字串，此字串是查詢設定檔的 XML 標記法。 如需無線設定檔之 XML 標記法的描述，請參閱 WLAN_profile架構。
呼叫端負責呼叫 WlanFreeMemory 函式，以釋放不再需要緩衝區時， pstrProfileXml 參數所配置給緩衝區指標的記憶體。
如果 pstrProfileXml 指定所有使用者設定檔， WlanGetProfile 呼叫端必須具有設定檔的讀取權限。 否則， WlanGetProfile 呼叫將會失敗，且傳回值為 ERROR_ACCESS_DENIED。 使用 WlanSetProfile 或 WlanSaveTemporaryProfile建立或儲存設定檔時，會建立所有使用者設定檔的許可權。
Windows 7：
如果在pstrProfileXml所指向的設定檔架構中傳回的 keyMaterial元素，如果呼叫 WlanGetProfile函式時，可能會要求純文字，並在輸入上由 pdwFlags參數所指向的值中設定WLAN_PROFILE_GET_PLAINTEXT_KEY旗標。
針對 WEP 金鑰，建立或更新設定檔時，可以使用 5 個 ASCII 字元或 10 個十六進位字元來設定純文字索引鍵。 不過，無論使用原始輸入來建立設定檔，WEP 設定檔都會在索引鍵中儲存 10 個十六進位字元。 因此，在 WlanGetProfile 函式傳回的設定檔中，純文字 WEP 索引鍵一律會以 10 個十六進位字元傳回。
若要讓WlanGetProfile呼叫傳回純文字索引鍵，必須在呼叫執行緒上設定來自WLAN_SECURABLE_OBJECT列舉類型的wlan_secure_get_plaiNtext_key許可權。 DACL 也必須包含 ACE，授與呼叫執行緒之存取權杖 的WLAN_READ_ACCESS 許可權。 根據預設，只允許擷取純文字金鑰的許可權給本機電腦上的 Administrators 群組成員。
如果呼叫執行緒缺少必要的許可權，WlanGetProfile函式會傳回pstrProfileXml參數所指向緩衝區中設定檔keyMaterial元素中的加密金鑰。 如果呼叫執行緒缺少必要的許可權，則不會傳回任何錯誤。
根據預設，pstrProfileXml所指向設定檔中傳回的keyMaterial元素會加密。 如果您的進程在相同電腦上的 LocalSystem 帳戶內容中執行，您可以呼叫 CryptUnprotectData 函式來取消加密金鑰資料。
Windows Server 2008 和 Windows Vista：pstrProfileXml所指向之設定檔架構中所傳回的 keyMaterial元素一律會加密。 如果您的進程是在 LocalSystem 帳戶的內容中執行，您可以呼叫 CryptUnprotectData 函式來取消加密金鑰資料。
Windows XP with SP3 和 Wireless LAN API for Windows XP with SP2： 金鑰資料永遠不會加密。
範例
下列範例會列舉本機電腦上的無線區域網路 介面、擷取每個無線區域網路 介面上特定無線設定檔的資訊，並列印所擷取的值。 也會列印查詢設定檔之 XML 表示的字串。
#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 _cdecl wmain(int argc, WCHAR **argv)
{
// 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;
/* variables used for WlanEnumInterfaces */
PWLAN_INTERFACE_INFO_LIST pIfList = NULL;
PWLAN_INTERFACE_INFO pIfInfo = NULL;
LPCWSTR pProfileName = NULL;
LPWSTR pProfileXml = NULL;
DWORD dwFlags = 0;
DWORD dwGrantedAccess = 0;
// Validate the parameters
if (argc < 2) {
wprintf(L"usage: %s <profile>\n", argv[0]);
wprintf(L" Gets a wireless profile\n");
wprintf(L" Example\n");
wprintf(L" %s \"Default Wireless\"\n", argv[0]);
exit(1);
}
pProfileName = argv[1];
wprintf(L"Information for profile: %ws\n\n", pProfileName);
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"WLAN_INTERFACE_INFO_LIST for this system\n");
wprintf(L"Num Entries: %lu\n", pIfList->dwNumberOfItems);
wprintf(L"Current Index: %lu\n\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\n");
dwResult = WlanGetProfile(hClient,
&pIfInfo->InterfaceGuid,
pProfileName,
NULL,
&pProfileXml,
&dwFlags,
&dwGrantedAccess);
if (dwResult != ERROR_SUCCESS) {
wprintf(L"WlanGetProfile failed with error: %u\n",
dwResult);
// You can use FormatMessage to find out why the function failed
} else {
wprintf(L" Profile Name: %ws\n", pProfileName);
wprintf(L" Profile XML string:\n");
wprintf(L"%ws\n\n", pProfileXml);
wprintf(L" dwFlags:\t 0x%x", dwFlags);
// if (dwFlags & WLAN_PROFILE_GET_PLAINTEXT_KEY)
// wprintf(L" Get Plain Text Key");
if (dwFlags & WLAN_PROFILE_GROUP_POLICY)
wprintf(L" Group Policy");
if (dwFlags & WLAN_PROFILE_USER)
wprintf(L" Per User Profile");
wprintf(L"\n");
wprintf(L" dwGrantedAccess: 0x%x", dwGrantedAccess);
if (dwGrantedAccess & WLAN_READ_ACCESS)
wprintf(L" Read access");
if (dwGrantedAccess & WLAN_EXECUTE_ACCESS)
wprintf(L" Execute access");
if (dwGrantedAccess & WLAN_WRITE_ACCESS)
wprintf(L" Write access");
wprintf(L"\n");
wprintf(L"\n");
}
}
}
if (pProfileXml != NULL) {
WlanFreeMemory(pProfileXml);
pProfileXml = 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 的無線區域網路 API |