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 SP3 및 Windows XP용 무선 LAN API SP2 사용: 프로필 이름은 네트워크의 SSID에서 자동으로 파생됩니다. 인프라 네트워크 프로필의 경우 프로필 이름은 네트워크의 SSID입니다. 임시 네트워크 프로필의 경우 프로필 이름은 임시 네트워크의 SSID 뒤에 가 잇 -adhoc는 것입니다.
[in] pReserved
다음에 사용하도록 예약됩니다. NULL로 설정해야 합니다.
[out] pstrProfileXml
쿼리된 프로필의 XML 표현인 문자열입니다. 미리 정의된 최대 문자열 길이가 없습니다.
[in, out, optional] pdwFlags
입력 시 요청에 대한 추가 정보를 제공하는 데 사용되는 주소 위치에 대한 포인터입니다. 이 매개 변수가 입력에서 NULL 이면 프로필 플래그에 대한 정보가 반환되지 않습니다. 출력 시 프로필 플래그를 수신하는 데 사용되는 주소 위치에 대한 포인터입니다.
WINDOWS XP SP3 및 Windows XP용 무선 LAN API SP2 사용: 사용자별 프로필은 지원되지 않습니다. 이 매개 변수를 NULL로 설정합니다.
pdwFlags 매개 변수는 다음 값이 포함된 주소 위치를 가리킬 수 있습니다.
| 값 | 의미 |
|---|---|
|
입력에서 이 플래그는 호출자가 무선 프로필에서 일반 텍스트 키를 검색하려고 했음을 나타냅니다. 호출 스레드에 필요한 권한이 있는 경우 WlanGetProfile 함수는 pstrProfileXml 매개 변수가 가리키는 버퍼에서 반환된 프로필의 keyMaterial 요소에 일반 텍스트 키를 반환합니다.
일반 텍스트 키를 반환하는 WlanGetProfile 호출의 경우 호출 스레드에서 WLAN_SECURABLE_OBJECT 열거형 형식의 wlan_secure_get_plaintext_key 권한을 설정해야 합니다. DACL에는 호출 스레드의 액세스 토큰에 대한 WLAN_READ_ACCESS 권한을 부여하는 ACE도 포함되어야 합니다. 기본적으로 일반 텍스트 키를 검색하는 권한은 로컬 컴퓨터에서 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.
함수가 실패하면 반환 값은 다음 반환 코드 중 하나일 수 있습니다.
| 반환 코드 | 설명 |
|---|---|
|
호출자에게 충분한 권한이 없습니다. pstrProfileXml 매개 변수가 모든 사용자 프로필을 지정하지만 호출자에게 프로필에 대한 읽기 권한이 없는 경우 이 오류가 반환됩니다. |
|
핸들이 잘못되었습니다. hClientHandle 매개 변수에 지정된 핸들이 핸들 테이블에 없는 경우 이 오류가 반환됩니다. |
|
매개 변수가 잘못되었습니다. 다음 조건이 발생하면 이 오류가 반환됩니다.
|
|
이 명령을 처리하는 데 사용할 수 있는 스토리지가 부족합니다. 시스템에서 프로필에 대한 메모리를 할당할 수 없는 경우 이 오류가 반환됩니다. |
|
strProfileName으로 지정된 프로필을 찾을 수 없습니다. |
|
다양한 RPC 및 기타 오류 코드. FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다. |
설명
WlanGetProfile 함수가 성공하면 pstrProfileXml 매개 변수가 가리키는 버퍼에 무선 프로필이 반환됩니다. 버퍼에는 쿼리된 프로필의 XML 표현인 문자열이 포함됩니다. 무선 프로필의 XML 표현에 대한 설명은 WLAN_profile 스키마를 참조하세요.
호출자는 버퍼가 더 이상 필요하지 않을 때 pstrProfileXml 매개 변수에 의해 에 할당된 메모리를 해제하기 위해 WlanFreeMemory 함수를 호출합니다.
pstrProfileXml이 모든 사용자 프로필을 지정하는 경우 WlanGetProfile 호출자는 프로필에 대한 읽기 권한이 있어야 합니다. 그렇지 않으면 반환 값이 ERROR_ACCESS_DENIEDWlanGetProfile 호출이 실패합니다. 모든 사용자 프로필에 대한 권한은 WlanSetProfile 또는 WlanSaveTemporaryProfile을 사용하여 프로필을 만들거나 저장할 때 설정됩니다.
Windows 7:
입력 시 pdwFlags 매개 변수가 가리키는 값에 설정된 WLAN_PROFILE_GET_PLAINTEXT_KEY 플래그를 사용하여 WlanGetProfile 함수를 호출하는 경우 pstrProfileXml이 가리키는 프로필 스키마에 반환된 keyMaterial 요소를 일반 텍스트로 요청할 수 있습니다.
WEP 키의 경우 프로필을 만들거나 업데이트할 때 5명의 ASCII 문자 또는 10명의 16진수 문자를 사용하여 일반 텍스트 키를 설정할 수 있습니다. 그러나 WEP 프로필은 원래 입력이 프로필을 만드는 데 사용된 내용에 관계없이 키에 106진수 문자로 저장됩니다. 따라서 WlanGetProfile 함수에서 반환된 프로필에서 일반 텍스트 WEP 키는 항상 106진수 문자로 반환됩니다.
일반 텍스트 키를 반환하는 WlanGetProfile 호출의 경우 호출 스레드에서 WLAN_SECURABLE_OBJECT 열거형 형식의 wlan_secure_get_plaintext_key 권한을 설정해야 합니다. DACL에는 호출 스레드의 액세스 토큰에 대한 WLAN_READ_ACCESS 권한을 부여하는 ACE도 포함되어야 합니다. 기본적으로 일반 텍스트 키를 검색하는 권한은 로컬 컴퓨터에서 Administrators 그룹의 구성원에게만 허용됩니다.
호출 스레드에 필요한 권한이 없는 경우 WlanGetProfile 함수는 pstrProfileXml 매개 변수가 가리키는 버퍼에서 반환된 프로필의 keyMaterial 요소에 암호화된 키를 반환합니다. 호출 스레드에 필요한 권한이 없는 경우 오류가 반환되지 않습니다.
기본적으로 pstrProfileXml이 가리키는 프로필에서 반환된 keyMaterial 요소는 암호화됩니다. 프로세스가 동일한 컴퓨터의 LocalSystem 계정 컨텍스트에서 실행되는 경우 CryptUnprotectData 함수를 호출하여 키 자료를 암호화 해제할 수 있습니다.
Windows Server 2008 및 Windows Vista: pstrProfileXml이 가리키는 프로필 스키마에 반환된 keyMaterial 요소는 항상 암호화됩니다. 프로세스가 LocalSystem 계정의 컨텍스트에서 실행되는 경우 CryptUnprotectData 함수를 호출하여 키 자료를 암호화 해제할 수 있습니다.
SP3이 있는 Windows XP 및 SP2를 사용하는 Windows XP용 무선 LAN API: 키 자료는 암호화되지 않습니다.
예제
다음 예제에서는 로컬 컴퓨터의 무선 LAN 인터페이스를 열거하고, 각 무선 LAN 인터페이스에서 특정 무선 프로필에 대한 정보를 검색하고, 검색된 값을 출력합니다. 쿼리된 프로필의 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 |
| 재배포 가능 파일 | SP2를 사용하는 Windows XP용 무선 LAN API |