WlanRegisterNotification 함수(wlanapi.h)

아티클
03/09/2024

중요

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

WlanRegisterNotification 함수는 모든 무선 인터페이스에서 알림을 등록 및 등록 취소하는 데 사용됩니다.

구문

DWORD WlanRegisterNotification(
  [in]            HANDLE                     hClientHandle,
  [in]            DWORD                      dwNotifSource,
  [in]            BOOL                       bIgnoreDuplicate,
  [in, optional]  WLAN_NOTIFICATION_CALLBACK funcCallback,
  [in, optional]  PVOID                      pCallbackContext,
  [in]            PVOID                      pReserved,
  [out, optional] PDWORD                     pdwPrevNotifSource
);

매개 변수

[in] hClientHandle

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

[in] dwNotifSource

등록할 알림 원본입니다. 이러한 플래그를 결합할 수 있습니다. 이 매개 변수가 WLAN_NOTIFICATION_SOURCE_NONE 설정되면 WlanRegisterNotification 은 모든 무선 인터페이스에서 알림을 등록 취소합니다.

이 매개 변수에 사용할 수 있는 값은 Wlanapi.h 및 L2cmn.h 헤더 파일에 정의되어 있습니다.

다음 표에서는 가능한 값을 보여 줍니다.

값	의미
WLAN_NOTIFICATION_SOURCE_NONE	알림을 등록 취소합니다.
WLAN_NOTIFICATION_SOURCE_ALL	802.1X 모듈에서 생성된 알림을 포함하여 운영 체제 버전에서 사용할 수 있는 모든 알림을 등록합니다. SP3가 있는 Windows XP 및 SP2를 사용하는 Windows XP용 무선 LAN API의 경우 dwNotifSource 를 WLAN_NOTIFICATION_SOURCE_ALL 설정하는 것은 dwNotifSource 를 WLAN_NOTIFICATION_SOURCE_ACM 설정하는 것과 기능적으로 동일합니다.
WLAN_NOTIFICATION_SOURCE_ACM	자동 구성 모듈에서 생성된 알림을 등록합니다. WINDOWS XP SP3 및 Windows XP용 무선 LAN API SP2 사용: wlan_notification_acm_connection_complete 및 wlan_notification_acm_disconnected 알림만 사용할 수 있습니다.
WLAN_NOTIFICATION_SOURCE_HNWK	무선 호스트 네트워크에서 생성된 알림을 등록합니다. 이 알림 원본은 무선 LAN 서비스가 설치된 Windows 7 및 Windows Server 2008 R2에서 사용할 수 있습니다.
WLAN_NOTIFICATION_SOURCE_ONEX	802.1X에서 생성된 알림을 등록합니다.
WLAN_NOTIFICATION_SOURCE_MSM	MSM에서 생성된 알림을 등록합니다. WLAN_NOTIFICATION_SOURCE_MSM 플래그가 dwNotifSource에 설정된 경우 wiFiControl 디바이스 기능이 필요합니다(앱 기능 선언 참조). 해당 기능이 부여되지 않은 경우 함수는 ERROR_ACCESS_DENIED 반환합니다. wiFiControl 디바이스 기능을 요청하려면 위치에 대한 액세스와 관련하여 사용자의 동의가 필요합니다. 자세한 내용은 Wi-Fi 액세스 및 위치에 대한 API 동작 변경을 참조하세요. WINDOWS XP SP3 및 Windows XP용 무선 LAN API SP2 사용: 이 값은 지원되지 않습니다.
WLAN_NOTIFICATION_SOURCE_SECURITY	보안 모듈에서 생성된 알림을 등록합니다. 현재 WLAN_NOTIFICATION_SOURCE_SECURITY 대한 알림이 정의되어 있지 않습니다. WINDOWS XP SP3 및 Windows XP용 무선 LAN API SP2 사용: 이 값은 지원되지 않습니다.
WLAN_NOTIFICATION_SOURCE_IHV	IHV(독립 하드웨어 공급업체)에서 생성한 알림을 등록합니다. WINDOWS XP SP3 및 Windows XP용 무선 LAN API SP2 사용: 이 값은 지원되지 않습니다.
WLAN_NOTIFICATION_SOURCE_DEVICE_SERVICE	디바이스 서비스에서 생성된 알림을 등록합니다.

WINDOWS XP SP3 및 Windows XP용 무선 LAN API SP2 사용: 이 매개 변수는 WLAN_NOTIFICATION_SOURCE_NONE, WLAN_NOTIFICATION_SOURCE_ALL 또는 WLAN_NOTIFICATION_SOURCE_ACM 설정해야 합니다.

[in] bIgnoreDuplicate

중복 알림을 무시할지 여부를 지정합니다. TRUE로 설정하면 이전 알림과 동일한 경우 알림이 클라이언트로 전송되지 않습니다.

WINDOWS XP SP3 및 Windows XP용 무선 LAN API SP2 사용: 이 매개 변수는 무시됩니다.

[in, optional] funcCallback

알림 콜백 함수의 형식을 정의하는 WLAN_NOTIFICATION_CALLBACK 형식입니다.

dwNotifSource 매개 변수가 모든 무선 인터페이스에서 알림을 등록 취소하도록 WLAN_NOTIFICATION_SOURCE_NONE 설정된 경우 이 매개 변수는 NULL일 수 있습니다.

[in, optional] pCallbackContext

알림과 함께 콜백 함수에 전달될 클라이언트 컨텍스트에 대한 포인터입니다.

[in] pReserved

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

[out, optional] pdwPrevNotifSource

이전에 등록된 알림 원본에 대한 포인터입니다.

반환 값

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

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

WLAN_NOTIFICATION_SOURCE_MSM 플래그가 dwNotifSource에 설정된 경우 wiFiControl 디바이스 기능이 필요합니다(앱 기능 선언 참조). 해당 기능이 부여되지 않은 경우 함수는 ERROR_ACCESS_DENIED 반환합니다. wiFiControl 디바이스 기능을 요청하려면 위치에 대한 액세스와 관련하여 사용자의 동의가 필요합니다. 자세한 내용은 Wi-Fi 액세스 및 위치에 대한 API 동작 변경을 참조하세요.

반환 코드	설명
ERROR_INVALID_PARAMETER	매개 변수가 잘못되었습니다. hClientHandle이 NULL이거나 유효하지 않거나 pReserved가 NULL이 아닌 경우 이 오류가 반환됩니다.
ERROR_INVALID_HANDLE	핸들 테이블에서 hClientHandle 핸들을 찾을 수 없습니다.
ERROR_NOT_ENOUGH_MEMORY	쿼리 결과에 대한 메모리를 할당하지 못했습니다.
ERROR_ACCESS_DENIED	WLAN_NOTIFICATION_SOURCE_MSM 플래그가 dwNotifSource에 설정된 경우 wiFiControl 디바이스 기능이 필요합니다(앱 기능 선언 참조). 해당 기능이 부여되지 않은 경우 함수는 ERROR_ACCESS_DENIED 반환합니다. wiFiControl 디바이스 기능을 요청하려면 위치에 대한 액세스와 관련하여 사용자의 동의가 필요합니다. 자세한 내용은 Wi-Fi 액세스 및 위치에 대한 API 동작 변경을 참조하세요.
RPC_STATUS	다양한 오류 코드.

설명

WlanRegisterNotification은 애플리케이션에서 모든 무선 인터페이스에서 알림을 등록 및 등록 취소하는 데 사용됩니다. 알림을 등록할 때 애플리케이션은 funcCallback 매개 변수가 가리키는 콜백 함수를 제공해야 합니다. 이 콜백 함수의 프로토타입은 WLAN_NOTIFICATION_CALLBACK. 이 콜백 함수는 WlanRegisterNotification 함수에 전달된 dwNotifSource 매개 변수에 등록된 알림을 받습니다. 콜백 함수는 알림에 대한 자세한 정보를 포함하는 첫 번째 매개 변수로 WLAN_NOTIFICATION_DATA 구조체에 대한 포인터를 사용하여 호출됩니다. 또한 콜백 함수는 pCallbackContext 매개 변수에서 WlanRegisterNotification 함수에 전달된 클라이언트 컨텍스트에 대한 포인터를 포함하는 두 번째 매개 변수를 받습니다.

dwNotifSource가 WLAN_NOTIFICATION_SOURCE_NONE 이외의 값이고 클라이언트가 콜백 함수를 제공하지 못하는 경우 WlanRegisterNotification 함수는 오류를 반환합니다.

등록되면 클라이언트가 핸들을 등록 취소하거나 닫을 때까지 알림을 사용할 수 있을 때마다 콜백 함수가 호출됩니다.

호출하는 애플리케이션이 호출 핸들을 닫거나(hClientHandle 매개 변수를 사용하여 WlanCloseHandle을 호출하여) 프로세스가 종료되는 경우 이 함수로 인한 알림을 수신하기 위한 등록은 자동으로 취소됩니다.

콜백 함수에서 WlanRegisterNotification 을 호출하지 마세요. dwNotifSource가 WLAN_NOTIFICATION_SOURCE_NONE 설정된 상태에서 WlanRegisterNotification이 호출될 때 클라이언트가 알림 콜백의 중간에 있는 경우(즉, 클라이언트가 알림에서 등록을 취소하는 경우) WlanRegisterNotification은 값을 반환하기 전에 콜백이 완료될 때까지 기다립니다. 콜백 함수 내에서 이 함수를 호출하면 호출이 완료되지 않습니다. 콜백 함수와 알림에서 등록을 취소하는 스레드가 모두 동일한 잠금을 획득하려고 하면 교착 상태가 발생할 수 있습니다. 또한 애플리케이션 DLL의 DllMain 함수에서 WlanRegisterNotification을 호출하지 마세요. 이로 인해 교착 상태가 발생할 수도 있습니다.

애플리케이션은 알림을 기다리는 대신 시간 초과 및 현재 인터페이스 상태를 쿼리할 수 있습니다.

WINDOWS XP SP3 및 Windows XP용 무선 LAN API SP2 사용: 알림은 Netman 서비스에서 처리됩니다. Netman 서비스를 사용하지 않도록 설정하거나 사용할 수 없는 경우 알림이 수신되지 않습니다. 적절한 기간 내에 알림이 수신되지 않으면 애플리케이션이 시간 초과되고 현재 인터페이스 상태를 쿼리해야 합니다.

요구 사항

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