NotifyAddrChange 函数 (iphlpapi.h)

项目
08/24/2023

只要表中发生了将 IPv4 地址映射到接口的更改， NotifyAddrChange 函数就会向调用方发送通知。

语法

IPHLPAPI_DLL_LINKAGE DWORD NotifyAddrChange(
  [out] PHANDLE      Handle,
  [in]  LPOVERLAPPED overlapped
);

parameters

[out] Handle

指向 HANDLE 变量的指针，该变量接收文件句柄以用于对 GetOverlappedResult 函数的后续调用。

警告不要关闭此句柄，也不要将其与完成端口相关联。

[in] overlapped

指向 OVERLAPPED 结构的指针，它通知调用方表中将 IP 地址映射到接口的任何更改。

返回值

如果函数成功，则如果调用方为句柄参数和重叠参数指定 NULL，则返回值NO_ERROR。如果调用方指定非 NULL 参数，则成功返回值ERROR_IO_PENDING。

如果函数失败，请使用 FormatMessage 获取返回错误的消息字符串。

返回代码	说明
ERROR_CANCELLED	上下文正在取消注册，因此立即取消了调用。
ERROR_INVALID_PARAMETER	传递的参数无效。如果句柄参数和重叠参数都不为 NULL，但调用进程无法写入输入参数指定的内存，则返回此错误。如果客户端已发出更改通知请求，则也会返回此错误，因此此重复请求将失败。
ERROR_NOT_ENOUGH_MEMORY	内存不足，无法完成操作。
ERROR_NOT_SUPPORTED	此错误在不支持此函数的 Windows 版本（如 Windows 98/95 和 Windows NT 4.0）上返回。

注解

The
可以通过两种方式调用 NotifyAddrChange 函数：

同步方法
异步方法

如果调用方为句柄参数和重叠参数指定 NULL，则对 NotifyAddrChange 的调用是同步的，并且将阻止，直到发生 IP 地址更改。在这种情况下，如果发生更改， 则 NotifyAddrChange 函数完成以指示发生了更改。

如果以同步方式调用 NotifyAddrChange 函数，则会在下次 IPv4 地址更改时发送通知，直到应用程序终止。

如果调用方指定句柄变量和 OVERLAPPED 结构，则 NotifyAddrChange 函数调用是异步的，调用方可以使用返回的句柄和 OVERLAPPED 结构，以使用 GetOverlappedResult 函数接收 IPv4 地址更改的异步通知。有关使用句柄和 OVERLAPPED 结构接收通知的信息，请参阅以下主题：

CancelIPChangeNotify 函数取消之前请求的 IPv4 地址和路由更改的通知，并成功调用 NotifyAddrChange 或 NotifyRouteChange 函数。

当应用程序收到更改通知后，应用程序可以调用 GetIpAddrTable 或 GetAdaptersAddresses 函数来检索 IPv4 地址表以确定更改的内容。如果通知应用程序并要求通知下一次更改，则必须再次调用 NotifyAddrChange 函数。

如果以异步方式调用 NotifyAddrChange 函数，则会在下一个 IPv4 地址更改时发送通知，直到应用程序通过调用 CancelIPChangeNotify 函数取消通知或应用程序终止。如果应用程序终止，系统将自动取消通知的注册。仍建议应用程序在终止之前显式取消任何通知。

在系统关闭或重新启动时，通知的任何注册都不会保留。

在 Windows Vista 及更高版本上， NotifyIpInterfaceChange 函数可用于注册以获取本地计算机上的 IPv4 和 IPv6 接口更改的通知。

示例

以下示例等待将 IP 地址映射到接口的表中发生更改。

#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <windows.h>

#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")

void main()
{
  OVERLAPPED overlap;
  DWORD ret;
    
  HANDLE hand = NULL;
  overlap.hEvent = WSACreateEvent();

  ret = NotifyAddrChange(&hand, &overlap);

  if (ret != NO_ERROR)
  {
    if (WSAGetLastError() != WSA_IO_PENDING)
    {
      printf("NotifyAddrChange error...%d\n", WSAGetLastError());            
      return;
    }
  }

  if ( WaitForSingleObject(overlap.hEvent, INFINITE) == WAIT_OBJECT_0 )
    printf("IP Address table changed..\n");
}

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	iphlpapi.h
Library	Iphlpapi.lib
DLL	Iphlpapi.dll