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

Статья
08/25/2023

Функция NotifyStableUnicastIpAddressTable извлекает стабильную одноадресную таблицу IP-адресов на локальном компьютере.

Синтаксис

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyStableUnicastIpAddressTable(
  [in]      ADDRESS_FAMILY                           Family,
  [in, out] PMIB_UNICASTIPADDRESS_TABLE              *Table,
  [in]      PSTABLE_UNICAST_IPADDRESS_TABLE_CALLBACK CallerCallback,
  [in]      PVOID                                    CallerContext,
  [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	Семейство адресов не указано. Если указан этот параметр, функция извлекает стабильную таблицу одноадресных IP-адресов, содержащую записи IPv4 и IPv6.
AF_INET 2	Семейство адресов IPv4. Если указан этот параметр, функция извлекает стабильную таблицу одноадресных IP-адресов, содержащую только записи IPv4.
AF_INET6 23	Семейство адресов IPv6. Если указан этот параметр, функция извлекает стабильную таблицу одноадресных IP-адресов, содержащую только записи IPv6.

[in, out] Table

Указатель на структуру MIB_UNICASTIPADDRESS_TABLE . Если NotifyStableUnicastIpAddressTable выполнен успешно , этот параметр возвращает стабильную одноадресную таблицу IP-адресов на локальном компьютере.

Когда NotifyStableUnicastIpAddressTable возвращает ERROR_IO_PENDING , указывающий на ожидание запроса ввода-вывода, стабильная одноадресная таблица IP-адресов возвращается в функцию в параметре CallerCallback .

[in] CallerCallback

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

[in] CallerContext

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

[in, out] NotificationHandle

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

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

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

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

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

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

Если функция NotifyStableUnicastIpAddressTable выполняется немедленно, возвращаемое значение NO_ERROR, а стабильная одноадресная ip-таблица возвращается в параметре Table . Вызывающее приложение должно освободить память, на которую указывает параметр Table , с помощью функции FreeMibTable , если сведения о MIB_UNICASTIPADDRESS_TABLE больше не нужны.

Все одноадресные IP-адреса, кроме адресов с телефонным подключением по запросу, считаются стабильными, только если они находятся в предпочтительном состоянии. Для обычной одноадресной записи IP-адреса это будет соответствовать члену DadState MIB_UNICASTIPADDRESS_ROW для IP-адреса IpDadStatePreferred. Каждый адрес с телефонным подключением по запросу определяет собственную метрику стабильности. В настоящее время эта функция учитывает только одноадресный IP-адрес, используемый клиентом Teredo на локальном компьютере.

Параметру Family необходимо задать значение AF_INET, AF_INET6 или AF_UNSPEC.

Если notifyStableUnicastIpAddressTable успешно выполняется и возвращает NO_ERROR, параметр Table возвращает стабильную одноадресную таблицу IP-адресов на локальном компьютере.

Функция NotifyStableUnicastIpAddressTable используется в основном приложениями, которые используют клиент Teredo.

Если одноадресный IP-адрес, используемый Teredo, доступен на локальном компьютере, но не находится в стабильном (квалифицированном) состоянии, NotifyStableUnicastIpAddressTable возвращает ERROR_IO_PENDING и стабильная одноадресная таблица IP-адресов в конечном итоге возвращается путем вызова функции в параметре CallerCallback . Если адрес Teredo недоступен или находится в стабильном состоянии, а другие одноадресные IP-адреса находятся в стабильном состоянии, функция в параметре CallerCallback никогда не будет вызываться.

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

Параметр	Описание
IN PVOID CallerContext	Параметр CallerContext , передаваемый в функцию NotifyStableUnicastIpAddressTable при регистрации для уведомлений.
IN PMIB_UNICASTIPADDRESS_TABLE AddressTable	Указатель на MIB_UNICASTIPADDRESS_TABLE , содержащий стабильную одноадресную таблицу IP-адресов на локальном компьютере.

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

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

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

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

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

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

Требования

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