notifyUnicastIpAddressChange 函数 (netioapi.h)

项目
02/29/2024

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上，头文件的组织已更改，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

收到接口通知时传递给 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 获取返回错误的消息字符串。

注解

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

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	通知类型。此成员可以是 Netioapi.h 头文件中定义的 MIB_NOTIFICATION_TYPE 枚举类型的值之一。

Callback 参数中指定的回调函数必须在调用 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 函数注册更改通知后，将继续发送这些通知，直到应用程序取消注册更改通知或应用程序终止。如果应用程序终止，系统将自动取消注册更改通知的任何注册。仍建议应用程序在终止之前显式取消注册更改通知。

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

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

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

要求

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