NotifyIpInterfaceChange 函数 (netioapi.h)

项目
08/25/2023

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上，头文件的组织方式已更改，并且 Ws2def.h 头文件中定义了此成员的可能值。请注意， Ws2def.h 头文件会自动包含在 Winsock2.h 中，永远不应直接使用。

当前支持的值是 AF_INET、 AF_INET6 和 AF_UNSPEC。

值	含义
AF_UNSPEC 0	地址系列未指定。指定此参数后，此函数将同时注册 IPv4 和 IPv6 更改通知。
AF_INET 2	Internet 协议版本 4 (IPv4) 地址系列。指定此参数后，此函数仅注册 IPv4 更改通知。
AF_INET6 23	Internet 协议版本 6 (IPv6) 地址系列。指定此参数时，此函数仅注册 IPv6 更改通知。

[in] Callback

指向发生更改时要调用的函数的指针。收到接口通知时，将调用此函数。

[in] CallerContext

收到接口通知时传递给 Callback 参数中指定的回调函数的用户上下文。

[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 获取返回错误的消息字符串。

注解

NotifyIpInterfaceChange 函数在 Windows Vista 及更高版本上定义。

Family 参数必须设置为 AF_INET、AF_INET6 或 AF_UNSPEC。

对 Callback 参数中指定的 回调函数的调用进行序列化。回调函数应定义为 VOID 类型的函数。传递给回调函数的参数包括：

参数	说明
IN PVOID CallerContext	注册通知时传递给 NotifyIpInterfaceChange 函数的 CallerContext 参数。
IN PMIB_IPINTERFACE_ROW 行可选	指向已更改的接口的MIB_IPINTERFACE_ROW 项的指针。将 NotificationType 参数中传递给回调函数的MIB_NOTIFICATION_TYPE值设置为 MibInitialNotification 时，此参数是 NULL 指针。只有在注册通知时，传递给 NotifyIpInterfaceChange 的 InitialNotification 参数设置为 TRUE 时，才会发生这种情况。
IN MIB_NOTIFICATION_TYPE NotificationType	通知类型。此成员可以是 Netioapi.h 头文件中定义的 MIB_NOTIFICATION_TYPE 枚举类型的值之一。

Callback 参数中指定的回调函数必须在调用 NotifyIpInterfaceChange 函数的应用程序所在的进程中实现。如果回调函数位于单独的 DLL 中，则应先加载 DLL，然后再调用 NotifyIpInterfaceChange 函数来注册更改通知。

当发生更改且 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 参数指向的内存。

若要取消注册更改通知，请调用 CancelMibChangeNotify2 函数，传递 NotifyIpInterfaceChange 返回的 NotificationHandle 参数。

应用程序无法从当前正在为同一 NotificationHandle 参数执行通知回调函数的线程的上下文调用 CancelMibChangeNotify2 函数。否则，执行该回调的线程将导致死锁。因此，不能在通知回调例程中直接调用 CancelMibChangeNotify2 函数。在更一般的情况下，执行 CancelMibChangeNotify2 函数的线程不能拥有执行通知回调操作的线程将等待的资源，因为这将导致类似的死锁。应从其他线程调用 CancelMibChangeNotify2 函数，接收通知回调的线程不依赖于该线程。

调用 NotifyIpInterfaceChange 函数注册更改通知后，将继续发送这些通知，直到应用程序取消更改通知的注册或应用程序终止。如果应用程序终止，系统将自动取消注册更改通知的任何注册。仍建议应用程序在终止之前显式取消注册更改通知。

在系统关闭或重新启动时，更改通知的任何注册都不会保留。

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	netioapi.h (包括 Iphlpapi.h)
Library	Iphlpapi.lib
DLL	Iphlpapi.dll