NotifyUnicastIpAddressChange 函数

项目
06/15/2023

NotifyUnicastIpAddressChange 函数注册驱动程序，以便在本地计算机上更改所有单播 IP 接口、单播 IPv4 地址或单播 IPv6 地址时收到通知。

语法

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

参数

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

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

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

地址系列当前支持以下值：
- AF_INET
  IPv4 地址系列。指定此值后，函数仅为单播 IPv4 地址更改通知注册驱动程序。
- AF_INET6
  IPv6 地址系列。指定此值后，函数仅为单播 IPv6 地址更改通知注册驱动程序。
- AF_UNSPEC
  未指定地址系列。指定此值后，函数会为单播 IPv4 和 IPv6 地址更改通知注册驱动程序。
回调 [in]
指向发生更改时要调用的函数的指针。收到单播 IP 地址通知时调用此函数。
CallerContext [in]
在收到接口通知时传递给 Callback 参数中指定的回调函数的用户上下文。
InitialNotification [in]
一个值，该值指示是否应在注册完成更改通知后立即调用回调。此初始通知并不指示单播 IP 地址发生了更改。此参数提供回调已注册的确认。
NotificationHandle [in， out]
用于返回句柄的指针，驱动程序稍后可以使用该句柄取消注册驱动程序更改通知。成功后，此参数中将返回通知句柄。如果发生错误，则返回 NULL 。

返回值

如果函数成功，NotifyUnicastIpAddressChange 将返回STATUS_SUCCESS。

如果函数失败， NotifyUnicastIpAddressChange 将返回以下错误代码之一：

返回代码	说明
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	在为更改通知注册驱动程序时传递给 NotifyUnicastIpAddressChange 函数的 CallerContext 参数。
IN PMIB_UNICASTIPADDRESS_ROW 行可选	指向已更改的单播 IP 地址 MIB_UNICASTIPADDRESS_ROW 条目的指针。将 NotificationType 参数中传递给回调函数的MIB_NOTIFICATION_TYPE值设置为 MibInitialNotification 时，此参数为 NULL 指针。只有在为更改通知注册驱动程序时传递给 NotifyUnicastIpAddressChange 的 InitialNotification 参数设置为 TRUE 时，才会发生这种情况。
IN MIB_NOTIFICATION_TYPE NotificationType	通知类型。此成员可以是 MIB_NOTIFICATION_TYPE 枚举类型的值之一。

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

要求

目标平台	通用
版本	在 Windows Vista 和更高版本的 Windows 操作系统中可用。
标头	Netioapi.h (包括 Netioapi.h)
库	Netio.lib
IRQL	< DISPATCH_LEVEL