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

Статья
03/15/2023

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

Синтаксис

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyUnicastIpAddressChange(
  [in]      ADDRESS_FAMILY                     Family,
  [in]      PUNICAST_IPADDRESS_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_INET	Зарегистрируйтесь только для одноадресных уведомлений об изменении IPv4-адресов.
AF_INET6	Зарегистрируйтесь только для одноадресных уведомлений об изменении IPv6-адресов.
AF_UNSPEC	Зарегистрируйтесь для получения уведомлений об изменении адресов IPv4 и IPv6 в одноадресной рассылке.

[in] Callback

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

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

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

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

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

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

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

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

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

Требования

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