NotifyRouteChange2 函数 (netioapi.h)
NotifyRouteChange2 函数注册本地计算机上的 IP 路由条目更改时会收到通知。
语法
IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyRouteChange2(
[in] ADDRESS_FAMILY AddressFamily,
[in] PIPFORWARD_CHANGE_CALLBACK Callback,
[in] PVOID CallerContext,
[in] BOOLEAN InitialNotification,
[in, out] HANDLE *NotificationHandle
);
parameters
[in] AddressFamily
要注册更改通知的地址系列。
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
收到 IP 路由通知时传递给 Callback 参数中指定的 回调 函数的用户上下文。
[in] InitialNotification
一个 值，该值指示是否应在更改通知注册完成后立即调用回调。 此初始通知并不表示 IP 路由条目发生了更改。 此参数用于确认回调已注册。
[in, out] NotificationHandle
用于返回句柄的指针，该句柄稍后可用于取消注册更改通知。 成功后，此参数中会返回通知句柄。 如果发生错误，则返回 NULL 。
返回值
如果函数成功，则返回值NO_ERROR。
如果函数失败，则返回值为以下错误代码之一。
| 返回代码 | 说明 |
|---|---|
|
遇到无效句柄时发生内部错误。 |
|
向该函数传递了无效参数。 如果 Family 参数不是 AF_INET、 AF_INET6或 AF_UNSPEC，则返回此错误。 |
|
内存不足。 |
|
使用 FormatMessage 获取返回错误的消息字符串。 |
注解
NotifyRouteChange2 函数在 Windows Vista 及更高版本上定义。
Family 参数必须设置为 AF_INET、AF_INET6 或 AF_UNSPEC。
对 Callback 参数中指定的 回调函数的调用进行序列化。 回调函数应定义为 VOID 类型的函数。 传递给回调函数的参数包括：
| 参数 | 说明 |
|---|---|
| IN PVOID CallerContext | 注册通知时传递给 NotifyRouteChange2 函数的 CallerContext 参数。 |
| IN PMIB_IPFORWARD_ROW2 行可选 | 指向已更改的 IP 路由条目 的MIB_IPFORWARD_ROW2 项的指针。 将 NotificationType 参数中传递给回调函数的MIB_NOTIFICATION_TYPE值设置为 MibInitialNotification 时，此参数是 NULL 指针。 只有在注册通知时，传递给 NotifyRouteChange2的 InitialNotification 参数设置为 TRUE 时，才会发生这种情况。 |
| IN MIB_NOTIFICATION_TYPE NotificationType | 通知类型。 此成员可以是 Netioapi.h 头文件中定义的 MIB_NOTIFICATION_TYPE 枚举类型的值之一。 |
Callback 参数中指定的回调函数必须在调用 NotifyRouteChange2 函数的应用程序所在的进程中实现。 如果回调函数位于单独的 DLL 中，则应先加载 DLL，然后再调用 NotifyRouteChange2 函数来注册更改通知。
当发生更改且 Row 参数不为 NULL 时收到回调函数时，指向 Row 参数中传递的MIB_IPFORWARD_ROW2结构的指针包含不完整的数据。 MIB_IPFORWARD_ROW2 结构中返回的信息仅是应用程序可以调用 GetIpForwardEntry2 函数来查询更改的 IP 路由的完整信息。 收到回调函数时，应用程序应分配MIB_IPFORWARD_ROW2结构，并使用接收的 Row 参数指向的MIB_IPFORWARD_ROW2结构中的 DestinationPrefix、NextHop、InterfaceLuid 和 InterfaceIndex 成员对其进行初始化。 应将指向此新初始化 MIB_IPFORWARD_ROW2 结构的指针传递给 GetIpForwardEntry2 函数，以检索有关已更改的 IP 路由的完整信息。
回调指示中使用的 Row 参数指向的内存由操作系统管理。 接收通知的应用程序绝不应尝试释放 Row 参数指向的内存。
调用 NotifyRouteChange2 函数注册更改通知后，将继续发送这些通知，直到应用程序取消更改通知的注册或应用程序终止。 如果应用程序终止，系统将自动取消注册更改通知的任何注册。 仍建议应用程序在终止之前显式取消注册更改通知。
如果系统关闭或重新启动，则更改通知的任何注册都不会保留。
若要取消更改通知的注册，请调用 CancelMibChangeNotify2 函数，传递 NotifyRouteChange2 返回的 NotificationHandle 参数。
应用程序无法从当前正在为同一 NotificationHandle 参数执行通知回调函数的线程的上下文调用 CancelMibChangeNotify2 函数。 否则，执行该回调的线程将导致死锁。 因此，不能在通知回调例程中直接调用 CancelMibChangeNotify2 函数。 在更一般的情况下，执行 CancelMibChangeNotify2 函数的线程不能拥有执行通知回调操作的线程将等待的资源，因为这将导致类似的死锁。 应从其他线程调用 CancelMibChangeNotify2 函数，接收通知回调的线程不依赖于该线程。
要求
| 最低受支持的客户端 | Windows Vista [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2008 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | netioapi.h (包括 Iphlpapi.h) |
| Library | Iphlpapi.lib |
| DLL | Iphlpapi.dll |