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

Статья
03/15/2023

Функция NotifyIpInterfaceChange регистрирует уведомления об изменениях во всех IP-интерфейсах, интерфейсах IPv4 или интерфейсах IPv6 на локальном компьютере.

Синтаксис

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyIpInterfaceChange(
  [in]      ADDRESS_FAMILY               Family,
  [in]      PIPINTERFACE_CHANGE_CALLBACK Callback,
  [in]      PVOID                        CallerContext,
  [in]      BOOLEAN                      InitialNotification,
  [in, out] HANDLE                       *NotificationHandle
);

Параметры

[in] Family

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

Возможные значения семейства адресов перечислены в файле заголовка 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_UNSPEC 0	Семейство адресов не указано. Если указан этот параметр, эта функция регистрирует уведомления об изменениях IPv4 и IPv6.
AF_INET 2	Семейство адресов IPv4. Если указан этот параметр, эта функция регистрируется только для уведомлений об изменениях IPv4.
AF_INET6 23	Семейство адресов IPv6. Если указан этот параметр, эта функция регистрирует только уведомления об изменениях IPv6.

[in] Callback

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

[in] CallerContext

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

[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 , передаваемый функции NotifyIpInterfaceChange при регистрации для уведомлений.
IN PMIB_IPINTERFACE_ROW Row (НЕОБЯЗАТЕЛЬНО)	Указатель на запись MIB_IPINTERFACE_ROW для измененного интерфейса. Этот параметр является указателем NULL , если значение MIB_NOTIFICATION_TYPE , передаваемое в параметре NotificationType в функцию обратного вызова, имеет значение MibInitialNotification. Это может произойти, только если параметр InitialNotification , переданный в NotifyIpInterfaceChange , был установлен в значение TRUE при регистрации для уведомлений.
IN MIB_NOTIFICATION_TYPE NotificationType	Тип уведомления. Этот член может быть одним из значений из типа перечисления MIB_NOTIFICATION_TYPE , определенного в файле заголовка Netioapi.h .

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

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

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

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

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

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

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

Требования

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