WlanSetProfile 함수(wlanapi.h)

아티클
03/04/2024

WlanSetProfile 함수는 특정 프로필의 콘텐츠를 설정합니다.

구문

DWORD WlanSetProfile(
  [in]           HANDLE     hClientHandle,
  [in]           const GUID *pInterfaceGuid,
  [in]           DWORD      dwFlags,
  [in]           LPCWSTR    strProfileXml,
  [in, optional] LPCWSTR    strAllUserProfileSecurity,
  [in]           BOOL       bOverwrite,
  [in]           PVOID      pReserved,
  [out]          DWORD      *pdwReasonCode
);

매개 변수

[in] hClientHandle

WlanOpenHandle 함수에 대한 이전 호출에서 얻은 클라이언트의 세션 핸들입니다.

[in] pInterfaceGuid

인터페이스의 GUID입니다.

[in] dwFlags

프로필에 설정할 플래그입니다.

SP3이 있는 Windows XP 및 WINDOWS XP용 무선 LAN API SP2: dwFlags는 0이어야 합니다. 사용자별 프로필은 지원되지 않습니다.

값	의미
0	프로필은 모든 사용자 프로필입니다.
WLAN_PROFILE_GROUP_POLICY 0x00000001	프로필은 그룹 정책 프로필입니다.
WLAN_PROFILE_USER 0x00000002	프로필은 사용자별 프로필입니다.

[in] strProfileXml

프로필의 XML 표현을 포함합니다. WLANProfile 요소는 루트 프로필 요소입니다. 샘플 프로필을 보려면 무선 프로필 샘플을 참조하세요. 미리 정의된 최대 문자열 길이가 없습니다.

WINDOWS XP SP3 및 Windows XP용 무선 LAN API SP2 사용: 제공된 프로필은 무선 프로필 호환성에 설명된 호환성 조건을 충족해야 합니다.

[in, optional] strAllUserProfileSecurity

모든 사용자 프로필에서 보안 설명자 문자열을 설정합니다. 프로필 권한에 대한 자세한 내용은 주의 섹션을 참조하세요.

dwFlags가 WLAN_PROFILE_USER 설정된 경우 이 매개 변수는 무시됩니다.

새 모든 사용자 프로필에 대해 이 매개 변수를 NULL 로 설정하면 wlan_secure_add_new_all_user_profiles 개체와 연결된 보안 설명자가 사용됩니다. WlanSetSecuritySettings 호출에서 보안 설명자를 수정하지 않은 경우 모든 사용자에게 새 모든 사용자 프로필에 대한 기본 권한이 있습니다. WlanGetSecuritySettings를 호출하여 wlan_secure_add_new_all_user_profiles 개체와 연결된 기본 권한을 가져옵니다.

기존 모든 사용자 프로필에 대해 이 매개 변수를 NULL 로 설정하면 프로필의 권한이 변경되지 않습니다.

이 매개 변수가 모든 사용자 프로필에 대해 NULL 이 아닌 경우 보안 설명자 개체를 만들고 문자열로 구문 분석한 후 프로필과 연결된 보안 설명자 문자열을 만들거나 수정합니다.

WINDOWS XP SP3 및 Windows XP용 무선 LAN API SP2 사용: 이 매개 변수는 NULL이어야 합니다.

[in] bOverwrite

이 프로필이 기존 프로필을 덮어쓸지 여부를 지정합니다. 이 매개 변수가 FALSE 이고 프로필이 이미 있는 경우 기존 프로필을 덮어쓰지 않고 오류가 반환됩니다.

[in] pReserved

다음에 사용하도록 예약됩니다. NULL로 설정해야 합니다.

[out] pdwReasonCode

프로필이 유효하지 않은 이유를 나타내는 WLAN_REASON_CODE 값입니다.

반환 값

함수가 성공하면 반환 값이 ERROR_SUCCESS.

함수가 실패하면 반환 값은 다음 반환 코드 중 하나일 수 있습니다.

반환 코드	설명
ERROR_ACCESS_DENIED	호출자에게 프로필을 설정할 수 있는 충분한 권한이 없습니다. dwFlags가 0으로 설정된 상태에서 호출되는 경우, 즉 모든 사용자 프로필을 설정할 때 WlanSetProfile은 wlan_secure_add_new_all_user_profiles 개체와 함께 저장된 DACL(임의 액세스 제어 목록)을 검색합니다. dwFlags가 WLAN_PROFILE_USER 설정된 상태에서 호출되는 경우, 즉 사용자별 프로필을 설정할 때 WlanSetProfile은 wlan_secure_add_new_per_user_profiles 개체와 함께 저장된 DACL(임의 액세스 제어 목록)을 검색합니다. 두 경우 모두 DACL에 호출 스레드의 액세스 토큰에 대한 WLAN_WRITE_ACCESS 권한을 부여하는 ACE(액세스 제어 항목)가 없는 경우 WlanSetProfile 은 ERROR_ACCESS_DENIED 반환합니다.
ERROR_ALREADY_EXISTS	strProfileXml 은 이미 존재하는 네트워크를 지정합니다. 일반적으로 이 반환 값은 bOverwrite 가 FALSE일 때 사용됩니다. 그러나 bOverwrite 가 TRUE 이고 dwFlags 가 기존 프로필에서 사용하는 프로필 형식과 다른 프로필 형식을 지정하는 경우 기존 프로필은 덮어쓰여지지 않으며 ERROR_ALREADY_EXISTS 반환됩니다.
ERROR_BAD_PROFILE	strProfileXml에서 지정한 프로필이 잘못되었습니다. 이 값이 반환되면 pdwReasonCode 는 프로필이 잘못된 이유를 지정합니다.
ERROR_INVALID_PARAMETER	다음 조건 중 하나가 발생했습니다. hClientHandle 이 NULL 이거나 잘못되었습니다. pInterfaceGuid 는 NULL입니다. pReserved 가 NULL이 아닙니다. strProfileXml 은 NULL입니다. [ConfigBlob] (/windows/desktop/eaphost/eaphostconfigschema-configblob-eaphostconfig-element). 프로필에 빈 ConfigBlob이 있어야 하는 경우 프로필에서 를 사용합니다 `<ConfigBlob>00</ConfigBlob>` . pdwReasonCode 는 NULL입니다. dwFlags 는 지정된 값 중 하나로 설정되지 않습니다. dwFlags 는 WLAN_PROFILE_GROUP_POLICY 설정되고 bOverwrite 는 FALSE로 설정됩니다.
ERROR_NO_MATCH	인터페이스는 프로필에 지정된 기능 중 하나 이상을 지원하지 않습니다. 예를 들어 프로필이 NIC에서 WPA만 지원할 때 WPA2 사용을 지정하는 경우 이 오류 코드가 반환됩니다. 또한 프로필이 NIC가 FIPS 모드를 지원하지 않을 때 FIPS 모드 사용을 지정하는 경우 이 오류 코드가 반환됩니다.
RPC_STATUS	다양한 오류 코드.

설명

WlanSetProfile 함수를 사용하여 새 무선 LAN 프로필을 추가하거나 기존 무선 LAN 프로필을 바꿀 수 있습니다.

그룹 정책 프로필 다음에 목록 맨 위에 새 프로필이 추가됩니다. 기존 프로필을 덮어쓰면 목록에서 프로필의 위치가 변경되지 않습니다. WINDOWS XP SP3 및 Windows XP용 무선 LAN API SP2 사용:

임시 프로필은 프로필 목록의 인프라 프로필 다음에 표시됩니다. 새 임시 프로필을 만들면 그룹 정책 및 인프라 프로필 다음에 임시 목록의 맨 위에 배치됩니다.

802.1X 게스트 프로필, WPS(무선 프로비저닝 서비스) 프로필 및 WPA-None(Wi-Fi Protected Access-None) 인증이 있는 프로필은 지원되지 않습니다. 즉, 네이티브 Wifi 함수를 사용하여 이러한 프로필을 만들거나 삭제하거나 열거하거나 액세스할 수 없습니다. 기본 설정 프로필 목록에 이미 있는 이러한 프로필은 목록에 남아 있으며 다른 프로필의 위치가 변경되지 않는 한 다른 프로필과 관련된 목록의 위치는 고정됩니다.

일반 텍스트 키가 포함된 프로필(즉, 보호된 요소가 있고 FALSE로 설정된 프로필)에서 WlanSetProfile을 호출할 수 있습니다. 프로필 저장소에 프로필을 저장하기 전에 키 자료가 자동으로 암호화됩니다. 이후에 WlanGetProfile을 호출하여 프로필 저장소에서 프로필을 검색하면 암호화된 키 자료가 반환됩니다. WINDOWS XP SP3 및 Windows XP용 무선 LAN API SP2 사용: 키 자료는 암호화되지 않습니다.

모든 사용자 프로필에는 읽기, 쓰기 및 실행의 세 가지 관련 권한이 있습니다. 사용자에게 읽기 권한이 있는 경우 사용자는 프로필 권한을 볼 수 있습니다. 사용자가 실행 액세스 권한이 있는 경우 사용자에게 읽기 권한이 있으며 사용자는 프로필을 사용하여 네트워크에 연결하고 네트워크 연결을 끊을 수도 있습니다. 사용자에게 쓰기 권한이 있는 경우 사용자는 실행 액세스 권한을 가지며 사용자는 프로필과 연결된 권한을 수정하고 삭제할 수도 있습니다.

다음은 보안 설명자 개체를 만들고 문자열로 구문 분석하는 절차를 설명합니다.

InitializeSecurityDescriptor를 호출하여 메모리에 보안 설명자를 만듭니다.
SetSecurityDescriptorOwner를 호출합니다.
InitializeAcl을 호출하여 메모리에 DACL(임의 액세스 제어 목록)을 만듭니다.
AddAccessAllowedAce 또는 AddAccessDeniedAce를 호출하여 DACL에 ACE(액세스 제어 항목)를 추가합니다. AccessMask 매개 변수를 적절하게 다음 중 하나로 설정합니다.
- WLAN_READ_ACCESS
- WLAN_EXECUTE_ACCESS
- WLAN_WRITE_ACCESS
SetSecurityDescriptorDacl을 호출하여 보안 설명자에 DACL을 추가합니다.
ConvertSecurityDescriptorToStringSecurityDescriptor를 호출하여 설명자를 문자열로 변환합니다.

그런 다음, WlanSetProfile을 호출할 때 ConvertSecurityDescriptorToStringSecurityDescriptor에서 반환된 문자열을 strAllUserProfileSecurity 매개 변수 값으로 사용할 수 있습니다.

네이티브 Wifi AutoConfig 서비스에서 사용하는 모든 무선 LAN 프로필에 대해 Windows는 사용자 지정 사용자 데이터의 개념을 유지 관리합니다. 이 사용자 지정 사용자 데이터는 처음에는 존재하지 않지만 WlanSetProfileCustomUserData 함수를 호출하여 설정할 수 있습니다. WlanSetProfile 함수를 호출하여 프로필이 수정될 때마다 사용자 지정 사용자 데이터가 비워지도록 다시 설정됩니다. 사용자 지정 사용자 데이터가 설정되면 WlanGetProfileCustomUserData 함수를 사용하여 이 데이터에 액세스할 수 있습니다.

모든 무선 LAN 함수는 프로필 작업을 수행할 때 무선 인터페이스에 대한 인터페이스 GUID가 필요합니다. 무선 인터페이스가 제거되면 WLANSVC(무선 LAN 서비스)에서 해당 상태가 지워지고 프로필 작업이 불가능합니다.

pInterfaceGuid 매개 변수에 지정된 무선 인터페이스가 시스템에서 제거된 경우(예: 제거된 USB 무선 어댑터) ERROR_INVALID_PARAMETER WlanSetProfile 함수가 실패할 수 있습니다.

netsh wlan add profile 명령은 명령줄에서 유사한 기능을 제공합니다. 자세한 내용은 무선 로컬 영역 네트워크(wlan)에 대한 Netsh 명령을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista, WINDOWS XP SP3 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	wlanapi.h(Wlanapi.h 포함)
라이브러리	Wlanapi.lib
DLL	Wlanapi.dll
재배포 가능 파일	WINDOWS XP용 무선 LAN API SP2