WlanScan 함수(wlanapi.h)

아티클
03/04/2024

참고

일부 정보는 상업용으로 출시되기 전에 상당 부분 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적이거나 묵시적인 보증도 하지 않습니다.

중요

이 API는 2024년 가을에 예정된 운영 체제 동작에 대한 향후 변경 내용의 영향을 받습니다. 자세한 내용은 Wi-Fi 액세스 및 위치에 대한 API 동작 변경을 참조하세요.

WlanScan 함수는 표시된 인터페이스에서 사용 가능한 네트워크에 대한 검사를 요청합니다.

구문

DWORD WlanScan(
  [in]           HANDLE               hClientHandle,
  [in]           const GUID           *pInterfaceGuid,
  [in, optional] const PDOT11_SSID    pDot11Ssid,
  [in, optional] const PWLAN_RAW_DATA pIeData,
                 PVOID                pReserved
);

매개 변수

[in] hClientHandle

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

[in] pInterfaceGuid

쿼리할 인터페이스의 GUID입니다.

로컬 컴퓨터에서 사용하도록 설정된 각 무선 LAN 인터페이스의 GUID는 WlanEnumInterfaces 함수를 사용하여 확인할 수 있습니다.

[in, optional] pDot11Ssid

검사할 네트워크의 SSID를 지정하는 DOT11_SSID 구조체에 대한 포인터입니다. 이 매개 변수는 선택적 요소입니다. NULL로 설정하면 반환된 목록에 사용 가능한 모든 네트워크가 포함됩니다. SP3이 있는 Windows XP 및 SP2를 사용하는 Windows XP용 무선 LAN API: 이 매개 변수는 NULL이어야 합니다.

[in, optional] pIeData

프로브 요청에 포함할 정보 요소에 대한 포인터입니다. 이 매개 변수는 클라이언트 프로비저닝 가용성 정보 및 802.1X 인증 요구 사항을 포함할 수 있는 WLAN_RAW_DATA 구조를 가리킵니다. SP3이 있는 Windows XP 및 SP2를 사용하는 Windows XP용 무선 LAN API: 이 매개 변수는 NULL이어야 합니다.

pReserved

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

반환 값

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

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

반환 코드	설명
ERROR_INVALID_PARAMETER	hClientHandle 이 NULL 이거나 잘못되었거나 , pInterfaceGuid 가 NULL이거나, pReserved 가 NULL이 아닙니다.
ERROR_INVALID_HANDLE	핸들 테이블에 hClientHandle 핸들을 찾을 수 없습니다.
RPC_STATUS	다양한 오류 코드.
ERROR_NOT_ENOUGH_MEMORY	쿼리 결과에 대한 메모리를 할당하지 못했습니다.

설명

WlanScan 함수는 네이티브 802.11 무선 LAN 드라이버가 사용 가능한 무선 네트워크를 검색하도록 요청합니다. 드라이버는 pDot11Ssid 및 pIeData 매개 변수에 전달된 값 및 구현에 따라 프로브 요청(활성 검사)을 보내거나 보내지 않을 수 있습니다.

pIeData 매개 변수가 NULL이 아닌 경우 드라이버는 검사 중에 프로브 요청을 보냅니다. 프로브 요청에는 pIeData 매개 변수가 가리키는 IE(정보 요소)가 포함됩니다. instance 경우 WPS(Wi-Fi 보호 설정) IE를 프로브 요청에 포함하여 WPS 지원 액세스 지점을 검색할 수 있습니다. pIeData 매개 변수가 가리키는 버퍼에는 요소 ID에서 시작하는 전체 IE가 포함되어야 합니다.

WlanScan 함수에 전달된 pIeData 매개 변수는 PSD(근접 서비스 검색) IE 데이터 항목을 포함하는 선택적 WLAN_RAW_DATA 구조체에 대한 포인터를 포함할 수 있습니다.

PSD IE를 저장하는 데 사용되는 경우 Wlanapi.h 헤더 파일에 정의된 DOT11_PSD_IE_MAX_DATA_SIZE 상수는 dwDataSize 멤버의 최대값입니다.

상수	값	Description
DOT11_PSD_IE_MAX_DATA_SIZE	240	PSD IE 데이터 항목의 최대 데이터 크기(바이트)입니다.

PSD IE 형식에 대한 설명을 포함하여 PSD IE에 대한 자세한 내용은 WlanSetPsdIEDataList 함수를 참조하세요.

WlanScan 함수가 호출되면 네이티브 802.11 무선 LAN 드라이버는 검사가 시작되기 전에 사용 가능한 무선 네트워크의 현재 목록을 플러시할 수 있습니다. 애플리케이션에서는 WlanScan 함수를 호출하면 이전 검사에서 WlanGetNetworkBssList 또는 WlanGetAvailableNetworkList 함수에서 반환된 사용 가능한 무선 네트워크의 기존 목록에 추가된다고 가정해서는 안 됩니다.

WlanScan 함수는 즉시 반환됩니다. 네트워크 검색이 완료되면 알림을 받도록 Windows Vista 이상 클라이언트는 WlanRegisterNotification을 호출하여 알림을 등록해야 합니다. WlanRegisterNotification 함수에 전달된 dwNotifSource 매개 변수에는 자동 구성 모듈에서 생성된 알림을 등록하기 위해 WLAN_NOTIFICATION_SOURCE_ACM 비트가 설정되어 있어야 합니다. WlanScan 함수 요청을 4초 안에 완료하려면 Windows 로고 요구 사항을 충족하는 무선 네트워크 드라이버가 필요합니다.

무선 LAN 서비스는 사용 가능한 무선 네트워크가 변경되면 알림을 보내지 않습니다. 무선 LAN 서비스는 여러 검사에서 사용 가능한 네트워크 목록의 변경 내용을 추적하지 않습니다. 현재 기본 동작은 무선 LAN 서비스가 무선 인터페이스 드라이버에게 60초마다 무선 네트워크를 검색하도록 요청하며, 경우에 따라(무선 네트워크에 이미 연결된 경우) 무선 LAN 서비스에서 검사를 전혀 요청하지 않는다는 것입니다. WlanScan 함수는 애플리케이션에서 무선 네트워크 변경 내용을 추적하는 데 사용할 수 있습니다. 애플리케이션은 먼저 WLAN_NOTIFICATION_SOURCE_ACM 알림에 등록해야 합니다. 그런 다음 WlanScan 함수를 호출하여 검사를 시작할 수 있습니다. 그러면 애플리케이션이 4초 후에 wlan_notification_acm_scan_complete 알림 또는 시간 제한을 받기 위해 기다려야 합니다. 그런 다음 애플리케이션은 WlanGetNetworkBssList 또는 WlanGetAvailableNetworkList 함수를 호출하여 사용 가능한 무선 네트워크 목록을 검색할 수 있습니다. 이 프로세스는 사용 가능한 무선 네트워크에 대한 변경 내용을 추적하는 애플리케이션을 통해 주기적으로 반복될 수 있습니다.

WlanScan 함수는 즉시 반환되며 SP3이 있는 Windows XP 또는 SP2를 사용하는 Windows XP용 무선 LAN API에서 검사가 완료되면 알림을 제공하지 않습니다.

스캔이 발생하는 동안 무선 인터페이스가 데이터 패킷을 보내고 받기가 더 어려워지므로 WlanScan 함수는 네트워크 검색이 완료될 때까지 대기 시간을 늘릴 수 있습니다.

요구 사항

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