WlanGetNetworkBssList 함수(wlanapi.h)

아티클
01/27/2024

참고

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

중요

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

WlanGetNetworkBssList 함수는 지정된 무선 LAN 인터페이스에서 무선 네트워크 또는 네트워크의 기본 BSS(서비스 집합) 항목 목록을 검색합니다.

구문

DWORD WlanGetNetworkBssList(
  [in]       HANDLE            hClientHandle,
  [in]       const GUID        *pInterfaceGuid,
  [optional] const PDOT11_SSID pDot11Ssid,
  [in]       DOT11_BSS_TYPE    dot11BssType,
  [in]       BOOL              bSecurityEnabled,
             PVOID             pReserved,
  [out]      PWLAN_BSS_LIST    *ppWlanBssList
);

매개 변수

[in] hClientHandle

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

[in] pInterfaceGuid

쿼리할 무선 LAN 인터페이스의 GUID에 대한 포인터입니다.

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

[optional] pDot11Ssid

BSS 목록이 요청된 네트워크의 SSID를 지정하는 DOT11_SSID 구조체에 대한 포인터입니다. 이 매개 변수는 선택적 요소입니다. NULL로 설정하면 반환된 목록에 무선 LAN 인터페이스에서 사용 가능한 모든 BSS 항목이 포함됩니다.

DOT11_SSID 구조체에 대한 포인터를 지정하는 경우 DOT11_SSID 구조체의 uSSIDLength 멤버에 지정된 SSID 길이는 Wlantypes.h 헤더 파일에 정의된 DOT11_SSID_MAX_LENGTH 보다 작거나 같아야 합니다. 또한 dot11BssType 매개 변수는 dot11_BSS_type_infrastructure 또는 dot11_BSS_type_independent 설정해야 하며 bSecurityEnabled 매개 변수를 지정해야 합니다.

[in] dot11BssType

네트워크의 BSS 유형입니다. BSS 목록에 대한 네트워크의 SSID가 지정되지 않은 경우 이 매개 변수는 무시됩니다( pDot11Ssid 매개 변수는 NULL임).

이 매개 변수는 Wlantypes.h 헤더 파일에 정의된 DOT11_BSS_TYPE 열거형에 정의된 다음 값 중 하나일 수 있습니다.

값	의미
dot11_BSS_type_infrastructure	인프라 BSS 네트워크.
dot11_BSS_type_independent	IBSS(독립 BSS) 네트워크(임시 네트워크)입니다.
dot11_BSS_type_any	모든 BSS 네트워크.

[in] bSecurityEnabled

네트워크에서 보안을 사용할 수 있는지 여부를 나타내는 값입니다. 이 매개 변수는 BSS 목록에 대한 네트워크의 SSID가 지정된 경우에만 유효합니다( pDot11Ssid 매개 변수는 NULL이 아님).

pReserved

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

[out] ppWlanBssList

WLAN_BSS_LIST 구조에서 반환된 BSS 항목 목록을 수신하는 포인터의 스토리지에 대한 포인터입니다.

반환된 WLAN_BSS_LIST 대한 버퍼는 호출이 성공하면 WlanGetNetworkBssList 함수에 의해 할당됩니다.

반환 값

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

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

반환 코드	설명
ERROR_INVALID_HANDLE	핸들 테이블에 hClientHandle 핸들을 찾을 수 없습니다.
ERROR_INVALID_PARAMETER	매개 변수가 잘못되었습니다. hClientHandle, pInterfaceGuid 또는 ppWlanBssList 매개 변수가 NULL인 경우 이 오류가 반환됩니다. pReserved가 NULL이 아닌 경우 이 오류가 반환됩니다. 이 오류는 hClientHandle, pDot11Ssid 매개 변수에 지정된 SSID 또는 dot11BssType 매개 변수에 지정된 BSS 형식이 유효하지 않은 경우에도 반환됩니다.
ERROR_NDIS_DOT11_POWER_STATE_INVALID	인터페이스와 연결된 라디오가 꺼져 있습니다. 라디오가 꺼져 있으면 BSS 목록을 사용할 수 없습니다.
ERROR_NOT_ENOUGH_MEMORY	이 요청을 처리하고 쿼리 결과에 대한 메모리를 할당하는 데 메모리가 부족합니다.
ERROR_NOT_FOUND	요소를 찾을 수 없습니다. pInterfaceGuid 매개 변수에 지정된 쿼리할 인터페이스의 GUID를 찾을 수 없는 경우 이 오류가 반환됩니다.
ERROR_NOT_SUPPORTED	요청이 지원되지 않습니다. SP3이 있는 Windows XP 또는 SP2 클라이언트가 있는 Windows XP용 무선 LAN API에서 이 함수를 호출한 경우 이 오류가 반환됩니다. WLAN AutoConfig 서비스를 사용하지 않도록 설정한 경우에도 이 오류가 반환됩니다.
ERROR_SERVICE_NOT_ACTIVE	WLAN AutoConfig 서비스가 시작되지 않았습니다.
RPC_STATUS	다양한 오류 코드.

설명

WlanGetNetworkBssList 함수는 지정된 인터페이스에서 액세스할 수 있는 각 무선 네트워크 또는 네트워크에 대한 기본 서비스 집합 목록을 검색합니다. 각 무선 네트워크에 대해 반환되는 정보 목록에는 인프라 BSS 네트워크에 대한 각 액세스 지점 또는 독립적인 BSS 네트워크(임시 네트워크)의 네트워크 피어에 대해 반환된 정보 요소 목록도 포함되어 있습니다. 정보는 ppWlanBssList 매개 변수의 WLAN_BSS_LIST 구조체에 대한 포인터로 반환됩니다. WLAN_BSS_LIST 구조체에는 항목 수와 WLAN_BSS_ENTRY 구조체 항목의 배열이 포함됩니다.

WlanGetNetworkBssList 함수에서 반환된 정보는 인프라 BSS 네트워크의 액세스 지점 또는 독립 BSS 네트워크(임시 네트워크)의 네트워크 피어에 의해 전송되므로 반환된 정보를 신뢰할 수 없습니다. WLAN_BSS_ENTRY 구조의 ulIeOffset 및 ulIeSize 멤버는 정보 요소 데이터 Blob 자체의 데이터가 아니라 WLAN_BSS_ENTRY 구조에서 정보 요소 데이터 Blob의 크기를 결정하는 데 사용해야 합니다. WlanGetNetworkBssList 함수는 ulIeOffset 멤버가 가리키는 정보 요소 데이터 Blob에 반환된 정보가 무선 LAN에 대한 IEEE 802.11 표준에 정의된 유효한 정보 요소인지 확인하지 않습니다.

pDot11Ssid 매개 변수가 NULL이 아닌 지정된 경우 지정된 dot11BssType 매개 변수를 인프라 BSS 네트워크의 dot11_BSS_type_infrastructure 또는 독립적인 BSS 네트워크(임시 네트워크)에 대한 dot11_BSS_type_independent 설정해야 합니다. dot11BssType 매개 변수가 dot11_BSS_type_any 설정된 경우 WlanGetNetworkBssList 함수는 ERROR_SUCCESS 반환하지만 BSS 항목은 반환되지 않습니다.

무선 LAN 인터페이스에서 모든 인프라 BSS 네트워크 및 독립 BSS 네트워크(임시 네트워크)의 목록을 반환하려면 pDot11Ssid 매개 변수를 NULL로 설정합니다. 무선 LAN 인터페이스가 무선 호스팅 네트워크로도 작동하는 경우 BSS 목록에는 무선 호스팅 네트워크에 대해 만든 BSS에 대한 항목이 포함됩니다.

WlanGetNetworkBssList 함수는 WLAN AutoConfig 서비스에서 빈 BSS 목록이 반환되면 ERROR_SUCCESS 반환합니다. WlanGetNetworkBssList 함수를 호출하는 애플리케이션은 WLAN_BSS_LIST 구조체에서 wlanBssEntries[0] 멤버에 액세스하기 전에 ppWlanBssList 매개 변수가 가리키는 WLAN_BSS_LISTdwNumberOfItems 멤버가 0이 아니라는 것을 검사 합니다.

WlanGetNetworkBssList 함수는 함수가 성공할 때 ppWlanBssList 매개 변수가 가리키는 버퍼에 반환되는 기본 서비스 집합 목록에 대한 메모리를 할당합니다. 버퍼가 더 이상 필요하지 않은 후 WlanFreeMemory 함수를 호출하여 ppWlanBssList 매개 변수가 가리키는 버퍼에 사용되는 메모리를 해제해야 합니다.

요구 사항

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