WlanHostedNetworkQuerySecondaryKey 함수(wlanapi.h)

아티클
08/28/2023

WlanHostedNetworkQuerySecondaryKey 함수는 무선 호스트 네트워크에서 사용하도록 구성된 보조 보안 키를 쿼리합니다.

구문

DWORD WlanHostedNetworkQuerySecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [out]           PDWORD                      pdwKeyLength,
  [out]           PUCHAR                      *ppucKeyData,
  [out]           PBOOL                       pbIsPassPhrase,
  [out]           PBOOL                       pbPersistent,
  [out, optional] PWLAN_HOSTED_NETWORK_REASON pFailReason,
                  PVOID                       pvReserved
);

매개 변수

[in] hClientHandle

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

[out] pdwKeyLength

WlanHostedNetworkQuerySecondaryKey 함수에 대한 호출이 성공하면 ppucKeyData 매개 변수가 가리키는 키 데이터 배열의 유효한 데이터 바이트 수를 지정하는 값에 대한 포인터입니다.

이 키 길이에는 키가 암호인 경우 종료되는 '\0'이 포함됩니다.

[out] ppucKeyData

WlanHostedNetworkQuerySecondaryKey 함수에 대한 호출이 성공하는 경우 보조 보안 키 데이터와 함께 반환된 버퍼에 대한 포인터를 수신하는 값에 대한 포인터입니다.

[out] pbIsPassPhrase

ppucKeyData 매개 변수가 가리키는 키 데이터 배열이 암호 형식인지 여부를 나타내는 부울 값에 대한 포인터입니다.

이 매개 변수가 TRUE이면 키 데이터 배열은 암호 형식입니다. 이 매개 변수가 FALSE이면 키 데이터 배열이 암호 형식이 아닙니다.

[out] pbPersistent

ppucKeyData 매개 변수가 가리키는 키 데이터 배열이 나중에 저장 및 재사용되거나 일회성 용도로만 사용되는지 여부를 나타내는 부울 값에 대한 포인터입니다.

이 매개 변수가 TRUE이면 키 데이터 배열을 나중에 저장하고 다시 사용할 수 있습니다. 이 매개 변수가 FALSE이면 키 데이터 배열은 일회성 용도로만 사용됩니다.

[out, optional] pFailReason

WlanHostedNetworkSetSecondaryKey 함수에 대한 호출이 실패하는 경우 실패 이유를 수신하는 값에 대한 선택적 포인터입니다. 실패 이유에 대한 가능한 값은 Wlanapi.h 헤더 파일에 정의된 WLAN_HOSTED_NETWORK_REASON 열거형 형식에서 가져옵니다.

pvReserved

다음에 사용하도록 예약됩니다. 이 매개 변수는 NULL이어야 합니다.

반환 값

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

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

반환 코드	설명
ERROR_INVALID_HANDLE	핸들이 잘못되었습니다. hClientHandle 매개 변수에 지정된 핸들이 핸들 테이블에 없는 경우 이 오류가 반환됩니다.
ERROR_INVALID_PARAMETER	매개 변수가 잘못되었습니다. 이 오류는 다음 조건 중 어느 것이 발생하는 경우 반환됩니다. hClientHandle 은 NULL입니다. pdwKeyLength 는 NULL입니다. ppucKeyData 가 NULL 이거나 잘못되었습니다. pbIsPassPhrase 가 NULL 이거나 잘못되었습니다. pbPersistent 는 NULL입니다. pvReserved 가 NULL이 아닙니다.
ERROR_INVALID_STATE	리소스가 요청된 작업을 수행하기에 올바른 상태가 아닙니다. 무선 호스트 네트워크가 종료 중이면 이 문제가 발생할 수 있습니다.
ERROR_OUTOFMEMORY	스토리지가 부족하여 이 작업을 완료할 수 없습니다.
ERROR_SERVICE_NOT_ACTIVE	서비스가 시작되지 않았습니다. WLAN AutoConfig 서비스가 실행되고 있지 않으면 이 오류가 반환됩니다.
기타	다양한 RPC 및 기타 오류 코드. FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다.

설명

WlanHostedNetworkQuerySecondaryKey 함수는 무선 LAN 서비스가 설치된 Windows 7 및 Windows Server 2008 R2에서 무선 호스트 네트워크를 지원하기 위해 추가된 네이티브 무선 API에 대한 확장입니다.

클라이언트 애플리케이션은 WlanHostedNetworkQuerySecondaryKey 함수를 호출하여 무선 호스트 네트워크에서 사용할 보조 보안 키를 쿼리합니다. 이 함수는 키 데이터, 키 길이, 암호인지 여부, 영구 또는 일회성 사용을 위한 키 정보를 반환합니다. 이 함수는 무선 호스트 네트워크의 상태 또는 속성을 변경하지 않습니다.

pbIsPassPhrase 매개 변수가 가리키는 값이 TRUE인 경우 보조 보안 키는 암호입니다. pbIsPassPhrase 매개 변수가 가리키는 값이 FALSE인 경우 보조 보안 키는 이진 키입니다.

ppucKeyData 매개 변수가 가리키는 버퍼에 반환된 보조 보안 키는 WPA2-Personal 인증에 사용되며 다음 형식 중 하나입니다.

8~63자의 ASCII 문자 배열로 구성된 키 암호입니다. pdwKeyLength 매개 변수가 가리키는 값에는 암호에 종결 '\0'이 포함됩니다. pdwKeyLength 매개 변수가 가리키는 값은 9~64 범위여야 합니다.
32바이트의 이진 키 데이터로 구성된 이진 키입니다. pdwKeyLength 매개 변수가 가리키는 값은 이진 키의 경우 32여야 합니다.

pbPersistent 매개 변수가 가리키는 값이 TRUE인 경우 보조 보안 키는 영구적입니다. 영구적이면 호스트된 네트워크가 이미 시작된 경우 보조 보안 키가 즉시 사용되고 나중에 Hosted Network가 시작될 때마다 다시 사용됩니다.

보조 보안 키가 영구로 지정되지 않은 경우 Hosted Network가 이미 시작된 경우 즉시 사용되거나 호스트된 네트워크가 시작된 다음에만 사용됩니다. Hosted Network가 중지된 후 이 보조 보안 키는 다시 사용되지 않으며 시스템에서 제거됩니다.

현재 구성된 보조 보안 키가 없으면 pdwKeyLength 매개 변수가 가리키는 반환된 값은 0이 되고 ppucKeyData 매개 변수에 반환된 값은 NULL이 됩니다. 이 경우 pbIsPassPhrase 및 pbPersistent 매개 변수에 반환된 값은 의미가 없습니다.

WlanHostedNetworkQuerySecondaryKey 함수가 성공하면 반환되는 ppucKeyData 매개 변수의 버퍼에 사용되는 메모리는 WlanFreeMemory 함수를 호출하여 사용한 후에 해제되어야 합니다.

모든 사용자는 WlanHostedNetworkQuerySecondaryKey 함수를 호출하여 호스트된 네트워크에서 사용되는 보조 보안 키를 쿼리할 수 있습니다. 그러나 무선 호스트 네트워크를 사용하도록 설정하는 기능은 도메인의 그룹 정책에 의해 제한될 수 있습니다.

Windows 7 이상에서 운영 체제는 호스트된 네트워크 지원 무선 어댑터가 컴퓨터에 있는 경우 가상 디바이스를 설치합니다. 이 가상 디바이스는 일반적으로 컴퓨터에 단일 무선 네트워크 어댑터가 있는 경우 디바이스 이름이 'Microsoft Virtual WiFi Miniport 어댑터'인 '무선 네트워크 연결 2'로 "네트워크 연결 폴더"에 표시됩니다. 이 가상 디바이스는 SoftAP(소프트웨어 액세스 지점) 연결을 수행하는 데만 사용되며 WlanEnumInterfaces 함수에서 반환된 목록에 없습니다. 이 가상 디바이스의 수명은 실제 무선 어댑터에 연결됩니다. 실제 무선 어댑터를 사용하지 않도록 설정하면 이 가상 디바이스도 제거됩니다. 이 기능은 무선 LAN 서비스가 설치된 Windows Server 2008 R2에서도 사용할 수 있습니다.

요구 사항


지원되는 최소 클라이언트	Windows 7 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 R2 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	wlanapi.h(Wlanapi.h 포함)
라이브러리	Wlanapi.lib
DLL	Wlanapi.dll