Функция SetUnicastIpAddressEntry

Статья
03/08/2023

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

Синтаксис

NETIOAPI_API SetUnicastIpAddressEntry(
  _In_ const MIB_UNICASTIPADDRESS_ROW *Row
);

Параметры

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

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

SetUnicastIpAddressEntry возвращает STATUS_SUCCESS, если функция выполнена успешно.

В случае сбоя функции SetUnicastIpAddressEntry возвращает один из следующих кодов ошибок:

Код возврата	Описание
STATUS_INVALID_PARAMETER	В функцию передан недопустимый параметр. Эта ошибка возвращается, если в параметре Row передается указатель NULL, члену addressMIB_UNICASTIPADDRESS_ROW структуры, на которую указывает параметр Row, не задан допустимый одноадресный IPv4-адрес или IPv6-адрес или не указаны оба элемента InterfaceLuid и InterfaceIndex структуры MIB_UNICASTIPADDRESS_ROW.
STATUS_NOT_FOUND	Не удалось найти указанный интерфейс. Эта ошибка возвращается, если функции не удается найти сетевой интерфейс, заданный элементом InterfaceLuid или InterfaceIndex структуры MIB_UNICASTIPADDRESS_ROW, на которую указывает параметр Row .
STATUS_NOT_SUPPORTED	Запрос не поддерживается. Эта ошибка возвращается, если на локальном компьютере не расположен стек IPv4 и адрес IPv4 был указан в элементе Address структуры MIB_UNICASTIPADDRESS_ROW, на которую указывает параметр Row , или если на локальном компьютере не расположен стек IPv6, а адрес IPv6 был указан в элементе Address .
Другое	Используйте функцию FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки.

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

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

Драйвер должен инициализировать следующие элементы структуры MIB_UNICASTIPADDRESS_ROW, на которую указывает параметр Row .

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

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

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

Требования

Целевая платформа	Универсальное
Версия	Доступно в Windows Vista и более поздних версиях операционных систем Windows.
Заголовок	Netioapi.h (включая Netioapi.h)
Библиотека	Netio.lib
IRQL	< DISPATCH_LEVEL