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

Статья
08/24/2023

Функция NotifyRouteChange приводит к отправке уведомления вызывающей объекту при каждом изменении в таблице маршрутизации IPv4.

Синтаксис

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

Параметры

[out] Handle

Указатель на переменную HANDLE , которая получает дескриптор для использования в асинхронном уведомлении.

[in] overlapped

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

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

Если функция выполняется успешно, возвращаемое значение 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 и перекрывающихся параметров, вызов NotifyRouteChange является синхронным и будет блокироваться до тех пор, пока не будет изменена таблица маршрутизации IPv4. В этом случае, если происходит изменение, функция NotifyRouteChange завершается, чтобы указать, что произошло изменение.

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

Если вызывающий объект указывает переменную дескриптора и структуру OVERLAPPED , вызывающий объект может использовать возвращенный дескриптор со структурой OVERLAPPED для получения асинхронного уведомления об изменениях таблицы маршрутизации IPv4. Сведения об использовании дескриптора и структуры OVERLAPPED для получения уведомлений см. в следующих разделах:

Если приложение получает уведомление и требует уведомления для следующего изменения, необходимо снова вызвать функцию NotifyRouteChange .

Функция CancelIPChangeNotify отменяет уведомление об изменениях IP-адреса и маршрута, запрошенных ранее при успешных вызовах функций NotifyAddrChange или NotifyRouteChange .

После уведомления приложения об изменении приложение может вызвать функцию GetIpForwardTable или GetIpForwardTable2 , чтобы получить таблицу маршрутизации IPv4, чтобы определить, что изменилось. Если приложение получает уведомление и требует уведомления о следующем изменении, функция NotifyRouteChange должна быть вызвана снова.

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

Регистрация уведомления не сохраняется при завершении работы или перезагрузке системы.

В Windows Vista и более поздних версиях функцию NotifyRouteChange2 можно использовать для регистрации для получения уведомлений об изменениях в таблице маршрутизации 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 = NotifyRouteChange(&hand, &overlap);

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

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

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	iphlpapi.h
Библиотека	Iphlpapi.lib
DLL	Iphlpapi.dll