Функция NotifyAddrChange (iphlpapi.h)

Статья
08/24/2023

Функция NotifyAddrChange вызывает уведомление при каждом изменении в таблице, которая сопоставляет IPv4-адреса с интерфейсами.

Синтаксис

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

Параметры

[out] Handle

Указатель на переменную HANDLE , которая получает дескриптор файла для использования в последующем вызове функции GetOverlappedResult .

Предупреждение Не закрывайте этот дескриптор и не связывайте его с портом завершения.

[in] overlapped

Указатель на структуру OVERLAPPED , которая уведомляет вызывающий объект о любых изменениях в таблице, которая сопоставляет IP-адреса с интерфейсами.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение NO_ERROR, если вызывающий объект задает ЗНАЧЕНИЕ NULL для параметров Handle и перекрывающихся параметров. Если вызывающий объект задает параметры, отличные от NULL , возвращаемое значение для успешного выполнения ERROR_IO_PENDING.

Если функция завершается сбоем, используйте FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки.

Код возврата	Описание
ERROR_CANCELLED	Контекст отменяется, поэтому вызов был немедленно отменен.
ERROR_INVALID_PARAMETER	Передан недопустимый параметр. Эта ошибка возвращается, если параметры Handle и перекрывающиеся параметры не имеют значения NULL, но память, указанная входными параметрами, не может быть записана вызывающим процессом. Эта ошибка также возвращается, если клиент уже сделал запрос на уведомление об изменении, поэтому этот повторяющийся запрос завершится ошибкой.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно доступной памяти для завершения операции.
ERROR_NOT_SUPPORTED	Эта ошибка возвращается в версиях Windows, в которых эта функция не поддерживается, например Windows 98/95 и Windows NT 4.0.

Если вызывающий объект задает значение NULL для параметров Handle и перекрывающихся параметров, вызов NotifyAddrChange является синхронным и будет блокироваться до изменения IP-адреса. В этом случае, если происходит изменение, функция NotifyAddrChange завершается, чтобы указать, что произошло изменение.

Если функция NotifyAddrChange вызывается синхронно, уведомление будет отправлено при следующем изменении IPv4-адреса до завершения работы приложения.

Если вызывающий объект указывает переменную дескриптора и структуру OVERLAPPED , то вызов функции NotifyAddrChange является асинхронным, и вызывающий объект может использовать возвращенный дескриптор со структурой OVERLAPPED для получения асинхронного уведомления об изменениях IPv4-адресов с помощью функции GetOverlappedResult . Сведения об использовании дескриптора и структуры 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
Header	iphlpapi.h
Библиотека	Iphlpapi.lib
DLL	Iphlpapi.dll