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

Статья
08/25/2023

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

Синтаксис

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API CreateIpForwardEntry2(
  [in] const MIB_IPFORWARD_ROW2 *Row
);

Параметры

[in] Row

Указатель на запись структуры MIB_IPFORWARD_ROW2 для записи IP-маршрута.

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

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

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

Код возврата	Описание
ERROR_ACCESS_DENIED	Отказано в доступе". Эта ошибка возвращается при нескольких условиях, которые включают следующее: у пользователя отсутствуют необходимые права администратора на локальном компьютере или приложение не выполняется в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени).
ERROR_INVALID_PARAMETER	В функцию передан недопустимый параметр. Эта ошибка возвращается, если в параметре Row передан указатель NULL, не указан элемент DestinationPrefixMIB_IPFORWARD_ROW2, на который указывает параметр Row, элемент NextHopMIB_IPFORWARD_ROW2, на который указывает параметр Row, или оба элемента InterfaceLuid или InterfaceIndexMIB_IPFORWARD_ROW2, на которые указывает Строка. параметр не указан. Эта ошибка также возвращается, если элемент PreferredLifetime , указанный в MIB_IPFORWARD_ROW2 , больше элемента ValidLifetime или если SitePrefixLength в MIB_IPFORWARD_ROW2 больше длины префикса, указанной в DestinationPrefix.
ERROR_NOT_FOUND	Не удалось найти указанный интерфейс. Эта ошибка возвращается, если не удалось найти сетевой интерфейс, заданный элементом InterfaceLuid или InterfaceIndexMIB_IPNET_ROW2 , на который указывает параметр Row .
ERROR_NOT_SUPPORTED	Запрос не поддерживается. Эта ошибка возвращается, если указанный интерфейс не поддерживает маршруты. Эта ошибка также возвращается, если на локальном компьютере нет стека IPv4 и AF_INET был указан в семействе адресов в элементе DestinationPrefixMIB_IPFORWARD_ROW2 , на который указывает параметр Row . Эта ошибка также возвращается, если на локальном компьютере нет стека IPv6 и AF_INET6 был указан для семейства адресов в элементе DestinationPrefix .
ERROR_OBJECT_ALREADY_EXISTS	Объект уже существует. Эта ошибка возвращается, если элемент DestinationPrefixMIB_IPFORWARD_ROW2 , на который указывает параметр Row , является дубликатом существующей записи IP-маршрута в интерфейсе, указанном элементом InterfaceLuid или InterfaceIndexMIB_IPFORWARD_ROW2.
Другое	Используйте FormatMessage , чтобы получить строку сообщения для возвращенной ошибки.

Функция CreateIpForwardEntry2 используется для добавления новой записи соседнего IP-адреса на локальном компьютере. Функция InitializeIpForwardEntry должна использоваться для инициализации элементов записи структуры MIB_IPFORWARD_ROW2 со значениями по умолчанию. Затем приложение может изменить члены в записи MIB_IPFORWARD_ROW2 , которую оно хочет изменить, а затем вызвать функцию CreateIpForwardEntry2 .

Элемент DestinationPrefix в структуре MIB_IPFORWARD_ROW2 , на который указывает параметр Row , должен быть инициализирован допустимым префиксом адреса IPv4 или IPv6. Элемент NextHop в структуре MIB_IPFORWARD_ROW2 , на который указывает параметр Row , должен быть инициализирован допустимым IPv4- или IPv6-адресом и семейством. Кроме того, по крайней мере один из следующих элементов в структуре MIB_IPFORWARD_ROW2 , указываемой на параметр Row , должен быть инициализирован в интерфейсе: InterfaceLuid или InterfaceIndex.

Поля используются в указанном выше порядке. Поэтому если указан InterfaceLuid , то этот элемент используется для определения интерфейса, к которому добавляется запись IP-маршрута. Если для элемента InterfaceLuid не задано значение (значения этого элемента были равны нулю), то для определения интерфейса используется элемент InterfaceIndex .

Смещение метрики маршрута, указанное в элементе Metricструктуры MIB_IPFORWARD_ROW2 , на которую указывает параметр Row , представляет только часть полной метрики маршрута. Полная метрика — это сочетание смещения этой метрики маршрута, добавленной к метрике интерфейса, указанной в элементе MetricMIB_IPINTERFACE_ROW структуры связанного интерфейса. Приложение может получить метрику интерфейса, вызвав функцию GetIpInterfaceEntry .

Элементы Age и Origin структуры MIB_IPFORWARD_ROW2 , на которые указывает Строка , игнорируются при вызове функции CreateIpForwardEntry2 . Эти элементы задаются сетевым стеком и не могут быть заданы с помощью функции CreateIpForwardEntry2 .

Функция CreateIpForwardEntry2 завершится ошибкой, если элементы DestinationPrefix и NextHopMIB_IPFORWARD_ROW2 , на которые указывает параметр Row , являются дубликатом существующей записи IP-маршрута в интерфейсе, указанном в элементах InterfaceLuid или InterfaceIndex .

Функция CreateIpForwardEntry2 может вызываться только пользователем, вошедшего в систему как участник группы "Администраторы". Если метод CreateIpForwardEntry2 вызывается пользователем, не включаемым в группу Администраторы, вызов функции завершится ошибкой и ERROR_ACCESS_DENIED возвращается. Эта функция также может завершиться ошибкой из-за контроля учетных записей (UAC) в Windows Vista и более поздних версиях. Если приложение, содержащее эту функцию, выполняется пользователем, вошедшего в систему как участник группы администраторов, отличный от встроенного администратора, этот вызов завершится ошибкой, если приложение не было отмечено в файле манифеста параметром requestedExecutionLevel , для которого задано значение requireAdministrator. Если в приложении отсутствует этот файл манифеста, пользователь, вошедший в группу администраторов, отличный от встроенного администратора, должен выполнять приложение в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени) для успешного выполнения этой функции.

Требования

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