NotifyIpInterfaceChange 함수(netioapi.h)
NotifyIpInterfaceChange 함수는 로컬 컴퓨터의 모든 IP 인터페이스, IPv4 인터페이스 또는 IPv6 인터페이스 변경에 대한 알림을 받도록 등록합니다.
구문
IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyIpInterfaceChange(
[in] ADDRESS_FAMILY Family,
[in] PIPINTERFACE_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.
[in] Callback
변경이 발생할 때 호출할 함수에 대한 포인터입니다. 이 함수는 인터페이스 알림이 수신될 때 호출됩니다.
[in] CallerContext
인터페이스 알림이 수신될 때 콜백 매개 변수에 지정된 콜백 함수에 전달되는 사용자 컨텍스트입니다.
[in] InitialNotification
변경 알림 등록이 완료된 직후 콜백을 호출해야 하는지 여부를 나타내는 값입니다. 이 초기 알림은 IP 인터페이스에 대한 변경이 발생했음을 나타내지 않습니다. 콜백이 등록되었음을 확인하는 이 매개 변수의 목적입니다.
[in, out] NotificationHandle
나중에 변경 알림을 등록 취소하는 데 사용할 수 있는 핸들을 반환하는 데 사용되는 포인터입니다. 성공하면 이 매개 변수에 알림 핸들이 반환됩니다. 오류가 발생하면 NULL 이 반환됩니다.
반환 값
함수가 성공하면 반환 값이 NO_ERROR.
함수가 실패하면 반환 값은 다음 오류 코드 중 하나입니다.
| 반환 코드 | 설명 |
|---|---|
|
잘못된 핸들이 발생한 내부 오류가 발생했습니다. |
|
잘못된 매개 변수가 함수에 전달되었습니다. Family 매개 변수가 AF_INET, AF_INET6또는AF_UNSPEC 않은 경우 이 오류가 반환됩니다. |
|
메모리가 부족했습니다. |
|
FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다. |
설명
NotifyIpInterfaceChange 함수는 Windows Vista 이상에서 정의됩니다.
Family 매개 변수는 AF_INET, AF_INET6 또는 AF_UNSPEC 설정해야 합니다.
콜백 매개 변수에 지정된 콜 백 함수의 호출이 serialize됩니다. 콜백 함수는 VOID 형식의 함수로 정의되어야 합니다. 콜백 함수에 전달되는 매개 변수는 다음과 같습니다.
| 매개 변수 | Description |
|---|---|
| IN PVOID CallerContext | 알림을 등록할 때 NotifyIpInterfaceChange 함수에 전달된 CallerContext 매개 변수입니다. |
| IN PMIB_IPINTERFACE_ROW Row OPTIONAL | 변경된 인터페이스의 MIB_IPINTERFACE_ROW 항목에 대한 포인터입니다. 이 매개 변수는 NotificationType 매개 변수에서 콜백 함수에 전달된 MIB_NOTIFICATION_TYPE 값이 MibInitialNotification으로 설정된 경우 NULL 포인터입니다. 알림을 등록할 때 NotifyIpInterfaceChange에 전달된 InitialNotification 매개 변수가 TRUE로 설정된 경우에만 발생할 수 있습니다. |
| IN MIB_NOTIFICATION_TYPE NotificationType | 알림 유형입니다. 이 멤버는 Netioapi.h 헤더 파일에 정의된 MIB_NOTIFICATION_TYPE 열거형 형식의 값 중 하나일 수 있습니다. |
콜백 매개 변수에 지정된 콜백 함수는 NotifyIpInterfaceChange 함수를 호출하는 애플리케이션과 동일한 프로세스에서 구현되어야 합니다. 콜백 함수가 별도의 DLL에 있는 경우 변경 알림을 등록하기 위해 NotifyIpInterfaceChange 함수를 호출하기 전에 DLL을 로드해야 합니다.
변경이 발생하고 Row 매개 변수가 NULL이 아닌 경우 콜백 함수가 수신되면 Row 매개 변수에 전달된 MIB_IPINTERFACE_ROW 구조체에 대한 포인터에 불완전한 데이터가 포함됩니다. MIB_IPINTERFACE_ROW 구조에서 반환되는 정보는 애플리케이션이 GetIpInterfaceEntry 함수를 호출하여 변경된 IP 인터페이스에 대한 전체 정보를 쿼리할 수 있는 충분한 정보일 뿐입니다. 콜백 함수가 수신되면 애플리케이션은 MIB_IPINTERFACE_ROW 구조를 할당하고 받은 Row 매개 변수가 가리키는 MIB_IPINTERFACE_ROW 구조체의 Family, InterfaceLuid 및 InterfaceIndex 멤버를 사용하여 초기화해야 합니다. 새로 초기화된 이 MIB_IPINTERFACE_ROW 구조체에 대한 포인터를 GetIpInterfaceEntry 함수에 전달하여 변경된 IP 인터페이스에 대한 전체 정보를 검색해야 합니다.
콜백 표시에 사용되는 Row 매개 변수가 가리키는 메모리는 운영 체제에서 관리됩니다. 알림을 받는 애플리케이션은 Row 매개 변수가 가리키는 메모리를 해제하려고 시도해서는 안 됩니다.
변경 알림을 등록 취소하려면 NotifyIpInterfaceChange에서 반환된 NotificationHandle 매개 변수를 전달하는 CancelMibChangeNotify2 함수를 호출합니다.
애플리케이션은 현재 동일한 NotificationHandle 매개 변수에 대한 알림 콜백 함수를 실행 중인 스레드의 컨텍스트에서 CancelMibChangeNotify2 함수를 호출할 수 없습니다. 그렇지 않으면 해당 콜백을 실행하는 스레드가 교착 상태가 발생합니다. 따라서 CancelMibChangeNotify2 함수는 알림 콜백 루틴의 일부로 직접 호출되어서는 안 됩니다. 좀 더 일반적인 상황에서 CancelMibChangeNotify2 함수를 실행하는 스레드는 알림 콜백 작업을 실행하는 스레드가 유사한 교착 상태를 초래하기 때문에 대기할 리소스를 소유할 수 없습니다. CancelMibChangeNotify2 함수는 알림 콜백을 수신하는 스레드에 종속성이 없는 다른 스레드에서 호출되어야 합니다.
변경 알림을 등록하기 위해 NotifyIpInterfaceChange 함수가 호출되면 애플리케이션이 변경 알림을 등록 취소하거나 애플리케이션이 종료될 때까지 이러한 알림이 계속 전송됩니다. 애플리케이션이 종료되면 시스템은 변경 알림에 대한 등록을 자동으로 등록 취소합니다. 애플리케이션이 종료되기 전에 변경 알림을 명시적으로 등록 취소하는 것이 좋습니다.
변경 알림에 대한 등록은 시스템 종료 또는 다시 부팅에서 유지되지 않습니다.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows Vista [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2008 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | netioapi.h(Iphlpapi.h 포함) |
| 라이브러리 | Iphlpapi.lib |
| DLL | Iphlpapi.dll |