Функция SetIpForwardEntry2 (netioapi.h)
Функция SetIpForwardEntry2 задает свойства записи IP-маршрута на локальном компьютере.
Синтаксис
IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetIpForwardEntry2(
[in] const MIB_IPFORWARD_ROW2 *Route
);
Параметры
[in] Route
Указатель на запись структуры MIB_IPFORWARD_ROW2 для записи IP-маршрута. Для элемента DestinationPrefixMIB_IPFORWARD_ROW2 должен быть задан допустимый префикс назначения IP- адреса, для элемента NextHopMIB_IPFORWARD_ROW2 — допустимое семейство IP-адресов и IP-адрес, а также должен быть указан элемент InterfaceLuid или InterfaceIndexMIB_IPFORWARD_ROW2 .
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение будет NO_ERROR.
Если функция завершается сбоем, возвращаемое значение представляет собой один из следующих кодов ошибок.
| Код возврата | Описание |
|---|---|
|
Отказано в доступе". Эта ошибка возвращается при нескольких условиях, которые включают следующее: у пользователя отсутствуют необходимые права администратора на локальном компьютере или приложение не выполняется в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени). |
|
В функцию передан недопустимый параметр. Эта ошибка возвращается, если в параметре Route передан указатель NULL, не указан элемент DestinationPrefixMIB_IPFORWARD_ROW2, на который указывает параметр Route, элемент NextHopMIB_IPFORWARD_ROW2, на который указывает параметр Route, либо оба элемента InterfaceLuid или InterfaceIndexMIB_IPFORWARD_ROW2, на которые указывает Route. параметр не указан. |
|
Не удалось найти указанный интерфейс. Эта ошибка возвращается, если не удалось найти сетевой интерфейс, заданный элементом InterfaceLuid или InterfaceIndexMIB_IPFORWARD_ROW2 , на который указывает параметр Route . |
|
Используйте FormatMessage , чтобы получить строку сообщения для возвращенной ошибки. |
Комментарии
Функция SetIpForwardEntry2 определена в Windows Vista и более поздних версиях.
Функция SetIpForwardEntry2 используется для задания свойств существующей записи IP-маршрута на локальном компьютере.
Элемент DestinationPrefix в структуре MIB_IPFORWARD_ROW2 , на который указывает параметр Route , должен быть инициализирован допустимым префиксом IP-адреса и семейством. Элемент NextHop в структуре MIB_IPFORWARD_ROW2 , на который указывает параметр Route , должен быть инициализирован допустимым IP-адресом и семейством. Кроме того, по крайней мере один из следующих элементов в структуре MIB_IPFORWARD_ROW2 , указываемой на параметр Route , должен быть инициализирован для интерфейса: InterfaceLuid или InterfaceIndex.
Поля используются в указанном выше порядке. Поэтому если указан InterfaceLuid , то этот элемент используется для определения интерфейса, к которому добавляется одноадресный IP-адрес. Если для элемента InterfaceLuid не задано значение (значения этого элемента были равны нулю), то для определения интерфейса используется элемент InterfaceIndex .
Смещение метрики маршрута, указанное в элементе Метрикиструктуры MIB_IPFORWARD_ROW2 , на которую указывает параметр Route, представляет только часть полной метрики маршрута. Полная метрика — это сочетание смещения этой метрики маршрута, добавленной к метрике интерфейса, указанной в элементе MetricMIB_IPINTERFACE_ROW структуры связанного интерфейса. Приложение может получить метрику интерфейса, вызвав функцию GetIpInterfaceEntry .
Элементы Age и Origin структуры MIB_IPFORWARD_ROW2 , на которые указывает Строка , игнорируются при вызове функции SetIpForwardEntry2 . Эти элементы задаются сетевым стеком и не могут быть изменены с помощью функции SetIpForwardEntry2 .
Функция SetIpForwardEntry2 завершится ошибкой , если элементы DestinationPrefix и NextHopMIB_IPFORWARD_ROW2 , на которые указывает параметр Route, не соответствуют записи IP-маршрута в указанном интерфейсе.
Функция SetIpForwardEntry2 может вызываться только пользователем, вошедшего в систему как участник группы Администраторы. Если метод SetIpForwardEntry2 вызывается пользователем, не включаемым в группу Администраторы, вызов функции завершится ошибкой и ERROR_ACCESS_DENIED возвращается.
Функция SetIpForwardEntry2 также может завершиться сбоем из-за контроля учетных записей (UAC) в Windows Vista и более поздних версиях. Если приложение, содержащее эту функцию, выполняется пользователем, вошедшего в систему как участник группы администраторов, отличный от встроенного администратора, этот вызов завершится ошибкой, если приложение не было отмечено в файле манифеста параметром requestedExecutionLevel , для которого задано значение requireAdministrator. Если в приложении отсутствует этот файл манифеста, пользователь, вошедший в группу администраторов, отличный от встроенного администратора, должен выполнять приложение в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени) для успешного выполнения этой функции.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows Vista [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 [только классические приложения] |
| Целевая платформа | Windows |
| Header | netioapi.h (включая Iphlpapi.h) |
| Библиотека | Iphlpapi.lib |
| DLL | Iphlpapi.dll |