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

Статья
08/25/2023

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

Синтаксис

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetUnicastIpAddressEntry(
  [in] const MIB_UNICASTIPADDRESS_ROW *Row
);

Параметры

[in] Row

Указатель на запись структуры MIB_UNICASTIPADDRESS_ROW для существующей записи одноадресного IP-адреса.

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

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

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

Код возврата	Описание
ERROR_ACCESS_DENIED	Отказано в доступе". Эта ошибка возвращается при нескольких условиях, которые включают следующее: у пользователя отсутствуют необходимые права администратора на локальном компьютере или приложение не выполняется в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени).
ERROR_INVALID_PARAMETER	В функцию передан недопустимый параметр. Эта ошибка возвращается, если в параметре Row передается указатель NULL, члену AddressMIB_UNICASTIPADDRESS_ROW, на который указывает параметр Row, не задан допустимый адрес IPv4 или IPv6 одноадресной рассылки, либо оба элемента InterfaceLuid или InterfaceIndexMIB_UNICASTIPADDRESS_ROW, на которые указывает параметр Row, были не указаны. Эта ошибка также возвращается для других ошибок в значениях, заданных для членов структуры MIB_UNICASTIPADDRESS_ROW . К этим ошибкам относятся следующие: если элемент ValidLifetime меньше элемента PreferredLifetime , Значение , если элемент PrefixOrigin имеет значение IpPrefixOriginUnchanged , а SuffixOrigin — не ipSuffixOriginUnchanged, если для элемента PrefixOrigin не задано значение IpPrefixOriginUnchanged , а для SuffixOrigin задано значение IpSuffixOriginUnchanged, если prefixOrigin Параметру member не присваивается значение из перечисления NL_PREFIX_ORIGIN , если член SuffixOrigin не имеет значения из перечисления NL_SUFFIX_ORIGIN или если для элемента OnLinkPrefixLength задано значение, превышающее длину IP-адреса, в битах (32 для IPv4-адреса одноадресной рассылки или 128 для одноадресного IPv6-адреса).
ERROR_NOT_FOUND	Не удалось найти указанный интерфейс. Эта ошибка возвращается, если не удалось найти сетевой интерфейс, заданный элементом InterfaceLuid или InterfaceIndexMIB_UNICASTIPADDRESS_ROW , на который указывает параметр Row .
ERROR_NOT_SUPPORTED	Запрос не поддерживается. Эта ошибка возвращается, если на локальном компьютере не находится стек IPv4, а адрес IPv4 указан в элементе AddressMIB_UNICASTIPADDRESS_ROW , на который указывает параметр Row , или на локальном компьютере отсутствует стек IPv6, а в элементе Address указан IPv6-адрес.
Другое	Используйте FormatMessage , чтобы получить строку сообщения для возвращенной ошибки.

Функция GetUnicastIpAddressEntry обычно используется для получения существующей записи структуры MIB_UNICASTIPADDRESS_ROW , которую необходимо изменить. Затем приложение может изменить члены в записи MIB_UNICASTIPADDRESS_ROW , которую оно хочет изменить, а затем вызвать функцию SetUnicastIpAddressEntry .

Приложение может вызвать функцию InitializeUnicastIpAddressEntry для инициализации элементов записи структуры MIB_UNICASTIPADDRESS_ROW со значениями по умолчанию перед внесением изменений. Однако приложение обычно сохраняет элемент InterfaceLuid или InterfaceIndex перед вызовом InitializeUnicastIpAddressEntry и восстанавливает один из этих элементов после вызова.

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

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

Если элемент OnLinkPrefixLengthMIB_UNICASTIPADDRESS_ROW , на который указывает параметр Row , имеет значение 255, то SetUnicastIpAddressEntry задаст свойства одноадресного IP-адреса, чтобы элемент OnLinkPrefixLength был равен длине IP-адреса. Поэтому для одноадресного IPv4-адреса OnLinkPrefixLength имеет значение 32, а OnLinkPrefixLength — 128 для одноадресного IPv6-адреса. Если это приведет к неправильной маске подсети для IPv4-адреса или неправильному префиксу ссылки для IPv6-адреса, приложение должно задать для этого элемента правильное значение перед вызовом SetUnicastIpAddressEntry.

Элементы DadState, ScopeId и CreationTimeStampструктуры MIB_UNICASTIPADDRESS_ROW , на которую указывает Строка , игнорируются при вызове функции SetUnicastIpAddressEntry . Эти элементы задаются сетевым стеком и не могут быть изменены с помощью функции SetUnicastIpAddressEntry . Элемент ScopeId автоматически определяется интерфейсом, в который был добавлен адрес.

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

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

Требования

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