NotifyIpInterfaceChange 函数

NotifyIpInterfaceChange 函数注册驱动程序,以便在本地计算机上所有 IP 接口、IPv4 接口或 IPv6 接口发生更改时收到通知。

语法

NETIOAPI_API NotifyIpInterfaceChange(
  _In_    ADDRESS_FAMILY               Family,
  _In_    PIPINTERFACE_CHANGE_CALLBACK Callback,
  _In_    PVOID                        CallerContext,
  _In_    BOOLEAN                      InitialNotification,
  _Inout_ HANDLE                       *NotificationHandle
);

参数

  • 家庭 [in]
    要为其注册更改通知的驱动程序的地址系列。

    Winsock2.h 头文件中列出了地址系列的可能值。 请注意,AF_地址系列和PF_协议系列常量的值 (相同,例如,AF_INET和PF_INET) ,因此可以使用任一常量。

    在 Windows Vista 和更高版本的 Windows 操作系统上,在 Ws2def.h 头文件中定义 Family 参数的可能值。 请注意,Ws2def.h 头文件自动包含在 Netioapi.h 中,不应直接使用 Ws2def.h。

    地址系列当前支持以下值:

    • AF_INET
      IPv4 地址系列。 指定此值后,此函数会将驱动程序注册为仅针对 IPv4 更改通知通知。

    • AF_INET6
      IPv6 地址系列。 指定此值后,此函数仅注册 IPv6 更改通知的驱动程序。

    • AF_UNSPEC
      地址系列未指定。 指定此值后,此函数会注册驱动程序,以便收到 IPv4 和 IPv6 更改的通知。

  • 回调 [in]
    指向发生更改时要调用的函数的指针。 收到接口通知时会调用此函数。

  • CallerContext [in]
    一个用户上下文,在收到接口通知时传递给 Callback 参数中指定的 回调 函数。

  • InitialNotification [in]
    一个 值,该值指示是否应在更改通知注册完成后立即调用回调。 此初始通知并不表示 IP 接口发生了更改。 此参数用于确认回调已注册。

  • NotificationHandle [in, out]
    用于返回句柄的指针,该句柄稍后可用于取消注册更改通知。 成功后,此参数中会返回通知句柄。 如果发生错误,则返回 NULL

返回值

如果函数成功,NotifyIpInterfaceChange 将返回STATUS_SUCCESS。

如果函数失败, NotifyIpInterfaceChange 将返回以下错误代码之一:

返回代码 说明
ERROR_INVALID_HANDLE

遇到无效句柄时发生内部错误。

STATUS_INVALID_PARAMETER

向该函数传递了无效参数。 如果 Family 参数不是AF_INET、AF_INET6或AF_UNSPEC,则返回此错误。

STATUS_NOT_ENOUGH_MEMORY

内存不足。

其他

使用 FormatMessage 函数获取返回错误的消息字符串。

注解

驱动程序必须将 Family 参数设置为 AF_INET、AF_INET6 或 AF_UNSPEC。

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

参数 说明

IN PVOID CallerContext

CallerContext 参数,在为更改通知注册驱动程序时传递给 NotifyIpInterfaceChange 函数。

IN PMIB_IPINTERFACE_ROW 可选

指向已更改的接口 的MIB_IPINTERFACE_ROW 项的指针。 将 NotificationType 参数中传递给回调函数的MIB_NOTIFICATION_TYPE值设置为 MibInitialNotification 时,此参数是 NULL 指针。 只有在为更改通知注册驱动程序时,传递给 NotifyIpInterfaceChangeInitialNotification 参数设置为 TRUE 时,才会发生这种情况。

IN MIB_NOTIFICATION_TYPE NotificationType

通知类型。 此成员可以是 MIB_NOTIFICATION_TYPE 枚举类型的值之一。

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

要求

目标平台

通用

版本

在 Windows Vista 和更高版本的 Windows 操作系统中可用。

标头

Netioapi.h (包括 Netioapi.h)

Netio.lib

IRQL

< DISPATCH_LEVEL

另请参阅

CancelMibChangeNotify2

GetIfEntry2

GetIfStackTable

GetIfTable2

GetInvertedIfStackTable

GetIpInterfaceEntry

InitializeIpInterfaceEntry

MIB_IF_ROW2

MIB_IF_TABLE2

MIB_IPINTERFACE_ROW

MIB_NOTIFICATION_TYPE

SetIpInterfaceEntry