WlanHostedNetworkSetSecondaryKey 함수(wlanapi.h)

아티클
08/28/2023

WlanHostedNetworkSetSecondaryKey 함수는 무선 호스트 네트워크에서 사용할 보조 보안 키를 구성합니다.

구문

DWORD WlanHostedNetworkSetSecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [in]            DWORD                       dwKeyLength,
  [in]            PUCHAR                      pucKeyData,
  [in]            BOOL                        bIsPassPhrase,
  [in]            BOOL                        bPersistent,
  [out, optional] PWLAN_HOSTED_NETWORK_REASON pFailReason,
                  PVOID                       pvReserved
);

매개 변수

[in] hClientHandle

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

[in] dwKeyLength

pucKeyData 매개 변수가 가리키는 키 데이터 배열의 유효한 데이터 바이트 수입니다. 이 키 길이는 키가 암호인 경우 종료되는 '\0'을 포함해야 합니다.

[in] pucKeyData

키 데이터가 포함된 버퍼에 대한 포인터입니다. 버퍼의 유효한 데이터 바이트 수는 dwKeyLength 매개 변수에 지정된 값 이상이어야 합니다.

[in] bIsPassPhrase

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

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

[in] bPersistent

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

이 매개 변수가 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입니다. pucKeyData 는 NULL입니다. pucKeyData 는 올바른 형식의 유효한 키를 가리키지 않습니다. pvReserved 가 NULL이 아닙니다.
ERROR_INVALID_STATE	리소스가 요청된 작업을 수행하기에 올바른 상태가 아닙니다. 무선 호스트 네트워크가 종료 중이면 이 문제가 발생할 수 있습니다.
ERROR_SERVICE_NOT_ACTIVE	서비스가 시작되지 않았습니다. WLAN AutoConfig 서비스가 실행되고 있지 않으면 이 오류가 반환됩니다.
기타	다양한 RPC 및 기타 오류 코드. FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다.

설명

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

클라이언트 애플리케이션은 WlanHostedNetworkSetSecondaryKey 함수를 호출하여 무선 호스트 네트워크에서 사용할 보조 보안 키를 구성합니다. 호출 애플리케이션이 호출 핸들을 닫거나(hClientHandle 매개 변수를 사용하여 WlanCloseHandle을 호출하여) 프로세스가 종료되는 경우 이 함수로 인한 호스트된 네트워크 변경은 자동으로 실행 취소되지 않습니다.

시작되면 무선 호스팅 네트워크를 사용하면 무선 피어가 기본 보안 키 외에도 이 보조 보안 키와 연결할 수 있습니다. 보조 보안 키는 항상 필요에 따라 사용자가 지정하지만 기본 보안 키는 보안 강도가 더 높은 운영 체제에서 생성됩니다.

pucKeyData 매개 변수가 가리키는 버퍼에 전달된 보조 보안 키는 WPA2-Personal 인증에 사용되며 다음 형식 중 하나여야 합니다.

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

유효한 보조 보안 키를 구성하려면 dwKeyLength 매개 변수가 올바른 범위에 있어야 하며 pucKeyData 매개 변수는 지정된 바이트 데이터를 포함하는 유효한 메모리 버퍼를 가리킵니다. 시스템에서 현재 구성된 보조 보안 키를 제거하려면 애플리케이션이 dwKeyLength 매개 변수에 0이 있고 pucKeyData 매개 변수에서 NULL이 있는 WlanHostedNetworkSetSecondaryKey 함수를 호출해야 합니다.

pucKeyData 매개 변수가 NULL이지만 dwKeyLength 매개 변수가 0이 아닌 경우 WlanHostedNetworkSetSecondaryKey 함수는 ERROR_INVALID_PARAMETER 반환합니다. dwKeyLength 매개 변수가 0이지만 pucKeyData 매개 변수가 NULL이 아닌 경우 WlanHostedNetworkSetSecondaryKey 함수도 ERROR_INVALID_PARAMETER 반환합니다.

보조 보안 키는 일반적으로 무선 호스트 네트워크가 시작되기 전에 설정됩니다. 그런 다음 호스트된 네트워크가 시작될 때 다음에 사용됩니다.

호스트된 네트워크가 시작된 후 보조 보안 키를 설정할 수도 있습니다. 이 경우 보조 보안 키가 즉시 사용됩니다. 이전 보조 보안 키를 사용하는 모든 클라이언트는 연결된 상태로 유지되지만 어떤 이유로든 연결이 끊어지거나 무선 호스트 네트워크가 다시 시작되는 경우 다시 연결할 수 없습니다.

bPersistent 매개 변수가 TRUE로 설정된 경우 보조 보안 키를 영구로 지정할 수 있습니다. 영구로 지정된 경우 호스트된 네트워크가 이미 시작된 경우 보조 보안 키가 즉시 사용되고 나중에 Hosted Network가 시작될 때마다 다시 사용됩니다.

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

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

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