NotifyUnicastIpAddressChange 함수(netioapi.h)

아티클
08/25/2023

NotifyUnicastIpAddressChange 함수는 로컬 컴퓨터의 모든 유니캐스트 IP 인터페이스, 유니캐스트 IPv4 주소 또는 유니캐스트 IPv6 주소에 대한 변경 내용에 대한 알림을 받도록 등록합니다.

구문

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyUnicastIpAddressChange(
  [in]      ADDRESS_FAMILY                     Family,
  [in]      PUNICAST_IPADDRESS_CHANGE_CALLBACK Callback,
  [in]      PVOID                              CallerContext,
  [in]      BOOLEAN                            InitialNotification,
  [in, out] HANDLE                             *NotificationHandle
);

매개 변수

[in] Family

변경 알림을 등록할 주소 패밀리입니다.

주소 패밀리에 사용할 수 있는 값은 Winsock2.h 헤더 파일에 나열됩니다. AF_ 주소 패밀리 및 PF_ 프로토콜 패밀리 상수의 값은 동일하므로(예: AF_INET 및 PF_INET) 두 상수를 모두 사용할 수 있습니다.

Windows Vista 이상용으로 릴리스된 Windows SDK 헤더 파일의 organization 변경되었으며 이 멤버에 대한 가능한 값은 Ws2def.h 헤더 파일에 정의됩니다. Ws2def.h 헤더 파일은 Winsock2.h에 자동으로 포함되며 직접 사용하면 안 됩니다.

현재 지원되는 값은 AF_INET, AF_INET6 및 AF_UNSPEC.

값	의미
AF_INET	유니캐스트 IPv4 주소 변경 알림만 등록합니다.
AF_INET6	유니캐스트 IPv6 주소 변경 알림에만 등록합니다.
AF_UNSPEC	유니캐스트 IPv4 및 IPv6 주소 변경 알림 모두에 등록합니다.

[in] Callback

변경이 발생할 때 호출할 함수에 대한 포인터입니다. 이 함수는 유니캐스트 IP 주소 알림이 수신될 때 호출됩니다.

[in] CallerContext

인터페이스 알림이 수신될 때 콜백 매개 변수에 지정된 콜백 함수에 전달되는 사용자 컨텍스트입니다.

[in] InitialNotification

변경 알림 등록이 완료된 직후 콜백을 호출해야 하는지 여부를 나타내는 값입니다. 이 초기 알림은 유니캐스트 IP 주소에 대한 변경이 발생했음을 나타내지 않습니다. 콜백이 등록되었음을 확인하는 이 매개 변수의 목적입니다.

[in, out] NotificationHandle

나중에 변경 알림을 등록 취소하는 데 사용할 수 있는 핸들을 반환하는 데 사용되는 포인터입니다. 성공하면 이 매개 변수에 알림 핸들이 반환됩니다. 오류가 발생하면 NULL 이 반환됩니다.

반환 값

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

함수가 실패하면 반환 값은 다음 오류 코드 중 하나입니다.

반환 코드	설명
ERROR_INVALID_HANDLE	잘못된 핸들이 발생한 내부 오류가 발생했습니다.
ERROR_INVALID_PARAMETER	잘못된 매개 변수가 함수에 전달되었습니다. Family 매개 변수가 AF_INET, AF_INET6또는AF_UNSPEC 않은 경우 이 오류가 반환됩니다.
ERROR_NOT_ENOUGH_MEMORY	메모리가 부족했습니다.
기타	FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다.

설명

NotifyUnicastIpAddressChange 함수는 Windows Vista 이상에서 정의됩니다.

Family 매개 변수는 AF_INET, AF_INET6 또는 AF_UNSPEC 설정해야 합니다.

콜백 매개 변수에 지정된 콜 백 함수의 호출이 serialize됩니다. 콜백 함수는 VOID 형식의 함수로 정의되어야 합니다. 콜백 함수에 전달되는 매개 변수는 다음과 같습니다.

매개 변수	Description
IN PVOID CallerContext	알림을 등록할 때 NotifyUnicastIpAddressChange 함수에 전달된 CallerContext 매개 변수입니다.
PMIB_UNICASTIPADDRESS_ROW 행 선택 사항	변경된 유니캐스트 IP 주소의 MIB_UNICASTIPADDRESS_ROW 항목에 대한 포인터입니다. 이 매개 변수는 NotificationType 매개 변수에서 콜백 함수에 전달된 MIB_NOTIFICATION_TYPE 값이 MibInitialNotification으로 설정된 경우 NULL 포인터입니다. 알림을 등록할 때 NotifyUnicastIpAddressChange에 전달된 InitialNotification 매개 변수가 TRUE로 설정된 경우에만 발생할 수 있습니다.
IN MIB_NOTIFICATION_TYPE NotificationType	알림 유형입니다. 이 멤버는 Netioapi.h 헤더 파일에 정의된 MIB_NOTIFICATION_TYPE 열거형 형식의 값 중 하나일 수 있습니다.

콜백 매개 변수에 지정된 콜백 함수는 NotifyUnicastIpAddressChange 함수를 호출하는 애플리케이션과 동일한 프로세스에서 구현되어야 합니다. 콜백 함수가 별도의 DLL에 있는 경우 변경 알림을 등록하기 위해 NotifyUnicastIpAddressChange 함수를 호출하기 전에 DLL을 로드해야 합니다.

변경이 발생하고 Row 매개 변수가 NULL이 아닌 경우 콜백 함수가 수신되면 Row 매개 변수에 전달된 MIB_UNICASTIPADDRESS_ROW 구조체에 대한 포인터에는 불완전한 데이터가 포함됩니다. MIB_UNICASTIPADDRESS_ROW 구조에서 반환되는 정보는 애플리케이션이 GetUnicastIpAddressEntry 함수를 호출하여 변경된 IP 주소에 대한 전체 정보를 쿼리할 수 있는 충분한 정보일 뿐입니다. 콜백 함수가 수신되면 애플리케이션은 MIB_UNICASTIPADDRESS_ROW 구조를 할당하고 받은 Row 매개 변수가 가리키는 MIB_UNICASTIPADDRESS_ROW 구조체의 Address, InterfaceLuid 및 InterfaceIndex 멤버를 사용하여 초기화해야 합니다. 새로 초기화된 이 MIB_UNICASTIPADDRESS_ROW 구조체에 대한 포인터를 GetUnicastIpAddressEntry 함수에 전달하여 변경된 유니캐스트 IP 주소에 대한 전체 정보를 검색해야 합니다.

콜백 표시에 사용되는 Row 매개 변수가 가리키는 메모리는 운영 체제에서 관리됩니다. 알림을 받는 애플리케이션은 Row 매개 변수가 가리키는 메모리를 해제하려고 시도해서는 안 됩니다.

변경 알림을 등록하기 위해 NotifyUnicastIpAddressChange 함수가 호출되면 애플리케이션이 변경 알림을 등록 취소하거나 애플리케이션이 종료될 때까지 이러한 알림이 계속 전송됩니다. 애플리케이션이 종료되면 시스템은 변경 알림에 대한 등록을 자동으로 등록 취소합니다. 애플리케이션이 종료되기 전에 변경 알림을 명시적으로 등록 취소하는 것이 좋습니다.

시스템이 종료되거나 다시 부팅되면 변경 알림에 대한 등록이 유지되지 않습니다.

변경 알림을 등록 취소하려면 NotifyUnicastIpAddressChange에서 반환된 NotificationHandle 매개 변수를 전달하는 CancelMibChangeNotify2 함수를 호출합니다.

애플리케이션은 현재 동일한 NotificationHandle 매개 변수에 대한 알림 콜백 함수를 실행 중인 스레드의 컨텍스트에서 CancelMibChangeNotify2 함수를 호출할 수 없습니다. 그렇지 않으면 해당 콜백을 실행하는 스레드가 교착 상태가 발생합니다. 따라서 CancelMibChangeNotify2 함수는 알림 콜백 루틴의 일부로 직접 호출되어서는 안 됩니다. 좀 더 일반적인 상황에서 CancelMibChangeNotify2 함수를 실행하는 스레드는 알림 콜백 작업을 실행하는 스레드가 유사한 교착 상태를 초래하기 때문에 대기할 리소스를 소유할 수 없습니다. CancelMibChangeNotify2 함수는 알림 콜백을 수신하는 스레드에 종속성이 없는 다른 스레드에서 호출되어야 합니다.

요구 사항

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