notifyUnicastIpAddressChange 函数 (netioapi.h)
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。
| 值 | 含义 |
|---|---|
|
仅注册单播 IPv4 地址更改通知。 |
|
仅注册单播 IPv6 地址更改通知。 |
|
注册单播 IPv4 和 IPv6 地址更改通知。 |
[in] Callback
指向发生更改时要调用的函数的指针。 收到单播 IP 地址通知时，将调用此函数。
[in] CallerContext
收到接口通知时传递给 Callback 参数中指定的 回调 函数的用户上下文。
[in] InitialNotification
一个 值，该值指示是否应在注册完成更改通知后立即调用回调。 此初始通知并不表示单播 IP 地址发生了更改。 此参数的用途，用于确认回调已注册。
[in, out] NotificationHandle
用于返回句柄的指针，该句柄稍后可用于取消注册更改通知。 成功后，此参数中将返回通知句柄。 如果发生错误，则返回 NULL 。
返回值
如果函数成功，则返回值NO_ERROR。
如果函数失败，则返回值为以下错误代码之一。
| 返回代码 | 说明 |
|---|---|
|
遇到无效句柄时发生内部错误。 |
|
向该函数传递了无效参数。 如果 Family 参数不是 AF_INET、 AF_INET6或 AF_UNSPEC，则返回此错误。 |
|
内存不足。 |
|
使用 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 |
另请参阅
InitializeUnicastIpAddressEntry