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

Статья
08/25/2023

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

Синтаксис

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetIpInterfaceEntry(
  [in, out] PMIB_IPINTERFACE_ROW Row
);

Параметры

[in, out] Row

Указатель на запись структуры MIB_IPINTERFACE_ROW для интерфейса. На входных данных элементу FamilyMIB_IPINTERFACE_ROW необходимо задать значение AF_INET6 или AF_INET и указать элемент InterfaceLuid или InterfaceIndexMIB_IPINTERFACE_ROW . При успешном возвращении элемент InterfaceLuidMIB_IPINTERFACE_ROW заполняется, если указан элемент InterfaceIndexзаписи MIB_IPINTERFACE_ROW .

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

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

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

Код возврата	Описание
ERROR_ACCESS_DENIED	Отказано в доступе". Эта ошибка возвращается при нескольких условиях, которые включают следующее: у пользователя отсутствуют необходимые права администратора на локальном компьютере или приложение не работает в расширенной оболочке в качестве встроенного администратора (администратор запуска от имени администратора).
ERROR_FILE_NOT_FOUND	Системе не удается найти указанный файл. Эта ошибка возвращается, если luID сетевого интерфейса или индекс интерфейса, заданный элементом InterfaceLuid или InterfaceIndexMIB_IPINTERFACE_ROW , на который указывает параметр Row , не является значением на локальном компьютере.
ERROR_INVALID_PARAMETER	В функцию передан недопустимый параметр. Эта ошибка возвращается, если в параметре Row передается указатель NULL, то член СемействаMIB_IPINTERFACE_ROW, на который указывает параметр Row, не был указан как AF_INET или AF_INET6 либо оба элемента InterfaceLuid или InterfaceIndexMIB_IPINTERFACE_ROW, на которые указывает параметр Row, не были указаны.
ERROR_NOT_FOUND	Не удалось найти указанный интерфейс. Эта ошибка возвращается, если сетевой интерфейс, указанный элементом InterfaceLuid или InterfaceIndexMIB_IPINTERFACE_ROW на который указывает параметр Row , не соответствует семейству IP-адресов, указанному в элементе Семейства в структуре MIB_IPINTERFACE_ROW .
Другое	Используйте FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки.

При входных данных член Семейства в структуре MIB_IPINTERFACE_ROW , на которую указывает параметр Row , должен быть инициализирован для AF_INET или AF_INET6. Кроме того, во входных данных необходимо инициализировать по крайней мере один из следующих элементов в структуре MIB_IPINTERFACE_ROW , указываемой на параметр Row : InterfaceLuid или InterfaceIndex.

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

В выходных данных элемент InterfaceLuidструктуры MIB_IPINTERFACE_ROW , на который указывает параметр Row , заполняется, если указан InterfaceIndex .

Элементы MaxReassemblySize, MinRouterAdvertisementInterval, MaxRouterAdvertisementInterval , Connected, SupportsWakeUpPatterns, SupportsNeighborDiscovery, SupportsRouterDiscovery, ReachableTime, TransmitOffload и ReceiveOffloadструктуры MIB_IPINTERFACE_ROW , на которую указывает Row , игнорируются при вызове функции SetIpInterfaceEntry . Эти элементы задаются сетевым стеком и не могут быть изменены с помощью функции SetIpInterfaceEntry .

Как правило, приложение вызывает функцию GetIpInterfaceTable для получения записей IP-интерфейса на локальном компьютере или функцию GetIpInterfaceEntry , чтобы получить только запись ИНТЕРФЕЙСА IP для изменения. Затем можно изменить структуру MIB_IPINTERFACE_ROW для конкретной записи ИНТЕРФЕЙСА IP и передать указатель на эту структуру в функцию SetIpInterfaceEntry в параметре Row . Однако для IPv4 приложение не должно пытаться изменить элемент SitePrefixLengthструктуры MIB_IPINTERFACE_ROW . Для IPv4 элемент SitePrefixLength должен иметь значение 0.

Другим возможным способом изменения существующей записи IP-интерфейса является использование функции InitializeIpInterfaceEntry для инициализации полей записи структуры MIB_IPINTERFACE_ROW значениями по умолчанию. Затем задайте член Семейства и элементы InterfaceIndex или InterfaceLuid в структуре MIB_IPINTERFACE_ROW , на которую указывает параметр Row , в соответствии с IP-интерфейсом, который необходимо изменить. Затем приложение может изменить поля в записи MIB_IPINTERFACE_ROW , которое оно хочет изменить, а затем вызвать функцию SetIpInterfaceEntry . Однако для IPv4 приложение не должно пытаться изменить элемент SitePrefixLengthструктуры MIB_IPINTERFACE_ROW . Для IPv4 элемент SitePrefixLength должен иметь значение 0. При таком подходе следует соблюдать осторожность, так как единственный способ определить все изменяемые поля — сравнить поля в MIB_IPINTERFACE_ROW конкретной записи IP-интерфейса с полями, заданными функцией InitializeIpInterfaceEntry при инициализации MIB_IPINTERFACE_ROW значениями по умолчанию.

Непривилегированные одновременный доступ к нескольким сетям с разными требованиями к безопасности создает пробел в безопасности и позволяет непривилегному приложению случайно ретранслировать данные между двумя сетями. Типичный пример — одновременный доступ к виртуальной частной сети (VPN) и Интернету. Windows Server 2003 и Windows XP используют слабую модель узла, где RAS предотвращает такой одновременный доступ за счет увеличения метрики маршрута всех маршрутов по умолчанию через другие интерфейсы. Таким образом, весь трафик направляется через интерфейс VPN, нарушая другие сетевые подключения.

В Windows Vista и более поздних версиях модель надежного узла используется по умолчанию. Если исходный IP-адрес указан в поиске маршрута с помощью GetBestRoute2 или GetBestRoute, поиск маршрута ограничивается интерфейсом исходного IP-адреса. Изменение метрики маршрута с помощью RAS не оказывает никакого влияния, так как список потенциальных маршрутов даже не имеет маршрута для интерфейса VPN, что позволяет трафику в Интернет. Элемент DisableDefaultRoutesMIB_IPINTERFACE_ROW можно использовать для отключения с помощью маршрута по умолчанию в интерфейсе. Этот член может использоваться VPN-клиентами в качестве меры безопасности для ограничения раздельного туннелирования, если vpn-клиент не требует раздельного туннелирования. VPN-клиент может вызвать функцию SetIpInterfaceEntry , чтобы при необходимости задать для члена DisableDefaultRoutesзначение TRUE . VPN-клиент может запросить текущее состояние члена DisableDefaultRoutes , вызвав функцию GetIpInterfaceEntry .

The

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

Требования

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