Функция NotifyRouteChange2 (netioapi.h)

Статья
03/15/2023

Функция 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
);

Параметры

[in] AddressFamily

Семейство адресов, в котором регистрируется для получения уведомлений об изменениях.

Возможные значения для семейства адресов перечислены в файле заголовка Winsock2.h . Обратите внимание, что значения для семейства адресов AF_ и констант семейства PF_ протоколов идентичны (например, AF_INET и PF_INET), поэтому можно использовать либо константу.

В windows SDK, выпущенном для Windows Vista и более поздних версий, организация файлов заголовков изменилась, и возможные значения для этого элемента определяются в файле заголовка Ws2def.h . Обратите внимание, что файл заголовка Ws2def.h автоматически включается в Winsock2.h и никогда не должен использоваться напрямую.

В настоящее время поддерживаются значения AF_INET, AF_INET6 и AF_UNSPEC.

Значение	Значение
AF_INET	Зарегистрируйтесь только для уведомлений об изменении маршрута IPv4.
AF_INET6	Зарегистрируйтесь только для уведомлений об изменении маршрута IPv6.
AF_UNSPEC	Зарегистрируйтесь для уведомлений об изменении маршрута IPv4 и IPv6.

[in] Callback

Указатель на функцию, вызываемую при изменении. Эта функция будет вызываться при получении уведомления об IP-маршруте.

[in] CallerContext

Контекст пользователя, передаваемый в функцию обратного вызова, указанную в параметре Callback , при получении уведомления об IP-маршруте.

[in] InitialNotification

Значение типа , указывающее, следует ли вызывать обратный вызов сразу после завершения регистрации уведомления об изменениях. Это начальное уведомление не указывает, что в записи IP-маршрута произошло изменение. Назначение этого параметра для подтверждения регистрации обратного вызова.

[in, out] NotificationHandle

Указатель, используемый для возврата дескриптора, который позже можно использовать для отмены регистрации уведомления об изменениях. При успешном выполнении в этом параметре возвращается дескриптор уведомления. При возникновении ошибки возвращается значение NULL .

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

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

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

Код возврата	Описание
ERROR_INVALID_HANDLE	Произошла внутренняя ошибка при обнаружении недопустимого дескриптора.
ERROR_INVALID_PARAMETER	В функцию передан недопустимый параметр. Эта ошибка возвращается, если параметр Family не был AF_INET, AF_INET6 или AF_UNSPEC.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно памяти.
Другое	Используйте FormatMessage , чтобы получить строку сообщения для возвращенной ошибки.

Вызов функции обратного вызова, указанной в параметре Callback , сериализуется. Функция обратного вызова должна быть определена как функция типа VOID. В функцию обратного вызова передаются следующие параметры:

Параметр	Описание
IN PVOID CallerContext	Параметр CallerContext , передаваемый функции NotifyRouteChange2 при регистрации для уведомлений.
IN PMIB_IPFORWARD_ROW2 строка НЕОБЯЗАТЕЛЬНЫЙ	Указатель на запись MIB_IPFORWARD_ROW2 для записи IP-маршрута, которая была изменена. Этот параметр является указателем NULL , если значение MIB_NOTIFICATION_TYPE , передаваемое в параметре NotificationType функции обратного вызова, имеет значение MibInitialNotification. Это может произойти только в том случае, если параметр InitialNotification , переданный в NotifyRouteChange2 , был установлен в значение TRUE при регистрации для уведомлений.
IN MIB_NOTIFICATION_TYPE NotificationType	Тип уведомления. Этот элемент может быть одним из значений из типа перечисления MIB_NOTIFICATION_TYPE , определенного в файле заголовка Netioapi.h .

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

Если функция обратного вызова получена при изменении и параметр Row не имеет значения NULL, указатель на структуру MIB_IPFORWARD_ROW2 , переданную в параметре Row , содержит неполные данные. Сведений, возвращаемых в структуре MIB_IPFORWARD_ROW2 , достаточно, чтобы приложение может вызвать функцию GetIpForwardEntry2 , чтобы запросить полную информацию об измененном IP-маршруте. При получении функции обратного вызова приложение должно выделить структуру MIB_IPFORWARD_ROW2 и инициализировать ее с помощью элементов DestinationPrefix, NextHop, InterfaceLuid и InterfaceIndex в структуре MIB_IPFORWARD_ROW2 , на которую указывает полученный параметр Row . Чтобы получить полную информацию об измененном IP-маршруте, необходимо передать указатель на эту новую инициализированную структуру MIB_IPFORWARD_ROW2 функцию GetIpForwardEntry2 .

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

После вызова функции NotifyRouteChange2 для регистрации уведомлений об изменениях эти уведомления будут отправляться до тех пор, пока приложение не отменит регистрацию уведомлений об изменениях или не завершит работу приложения. В случае завершения работы приложения система автоматически отменит регистрацию для уведомлений об изменениях. По-прежнему рекомендуется явно отменить регистрацию для уведомлений об изменениях перед завершением работы приложения.

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

Чтобы отменить регистрацию уведомлений об изменениях, вызовите функцию CancelMibChangeNotify2 , передав параметр NotificationHandle , возвращенный NotifyRouteChange2.

Приложение не может вызвать функцию CancelMibChangeNotify2 из контекста потока, который в настоящее время выполняет функцию обратного вызова уведомления для того же параметра NotificationHandle . В противном случае поток, выполняющий этот обратный вызов, приведет к взаимоблокировке. Поэтому функцию CancelMibChangeNotify2 нельзя вызывать напрямую в рамках процедуры обратного вызова уведомления. В более общей ситуации поток, выполняющий функцию CancelMibChangeNotify2 , не может владеть ресурсом, для которого поток, выполняющий операцию обратного вызова уведомления, будет ждать, так как это приведет к аналогичной взаимоблокировке. Функция CancelMibChangeNotify2 должна вызываться из другого потока, от которого поток, получающий обратный вызов уведомления, не имеет зависимостей.

Требования


Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	netioapi.h (включая Iphlpapi.h)
Библиотека	Iphlpapi.lib
DLL	Iphlpapi.dll