Функция CreateUnicastIpAddressEntry
Функция CreateUnicastIpAddressEntry добавляет новую запись IP-адреса одноадресной рассылки на локальном компьютере.
Синтаксис
NETIOAPI_API CreateUnicastIpAddressEntry(
_In_ const MIB_UNICASTIPADDRESS_ROW *Row
);
Параметры
- Строка [in]
Указатель на запись структуры MIB_UNICASTIPADDRESS_ROW для записи одноадресного IP-адреса.
Возвращаемое значение
CreateUnicastIpAddressEntry возвращает STATUS_SUCCESS, если функция выполнена успешно.
Если функция завершается ошибкой, CreateUnicastIpAddressEntry возвращает один из следующих кодов ошибок:
| Код возврата | Description |
|---|---|
| STATUS_INVALID_PARAMETER | Недопустимый параметр был передан функции. Эта ошибка возвращается, если указатель NULL передается в параметре Row, член адреса MIB_UNICASTIPADDRESS_ROW структуры, указывающей на то, что параметр Row указывает на недопустимый ip-адрес одноадресной рассылки или IPv6, или члены InterfaceLuid и InterfaceIndex структуры MIB_UNICASTIPADDRESS_ROW были не указаны. Эта ошибка также возвращается для других ошибок в значениях, заданных для элементов в структуре MIB_UNICASTIPADDRESS_ROW. Эти ошибки включают следующие ситуации:
Возможные значения перечислений NL_PREFIX_ORIGIN и NL_SUFFIX_ORIGIN см. в MIB_UNICASTIPADDRESS_ROW. |
| STATUS_NOT_FOUND | Не удалось найти указанный интерфейс. Эта ошибка возвращается, если функция не может найти сетевой интерфейс, указанный членом InterfaceLuid или InterfaceIndex структуры MIB_UNICASTIPADDRESS_ROW, на которую указывает параметр Row . |
| STATUS_NOT_SUPPORTED | Запрос не поддерживается. Эта ошибка возвращается, если на локальном компьютере не находится стек IPv4, а IPv4-адрес был указан в элементе адреса структуры MIB_UNICASTIPADDRESS_ROW, на которую указывает параметр Row, или если на локальном компьютере не указан стек IPv6, а в члене адреса IPv6 указан адрес IPv6. |
| ERROR_OBJECT_ALREADY_EXISTS | Объект уже существует. Эта ошибка возвращается, если элемент адреса структуры MIB_UNICASTIPADDRESS_ROW, к которому указывает параметр Row, является дубликатом существующего одноадресного IP-адреса в интерфейсе, заданном членом InterfaceLuid или InterfaceIndex MIB_UNICASTIPADDRESS_ROW. |
| Другое | Используйте функцию FormatMessage, чтобы получить строку сообщения для возвращаемой ошибки. |
Замечания
Используйте функцию InitializeUnicastIpAddressEntry для инициализации элементов записи структуры MIB_UNICASTIPADDRESS_ROW со значениями по умолчанию. Затем драйвер может изменить элементы в записи MIB_UNICASTIPADDRESS_ROW, которую он хочет изменить, а затем вызвать функцию CreateUnicastIpAddressEntry .
При входе драйвер должен инициализировать следующие элементы структуры MIB_UNICASTIPADDRESS_ROW, на которые указывает параметр Row .
Адрес
Задайте допустимый ip-адрес и семейство одноадресной рассылки IPv4 или IPv6.InterfaceLuid или InterfaceIndex
Эти члены используются в порядке, указанном ранее. Таким образом, если указан InterfaceLuid , этот элемент используется для определения интерфейса для добавления ip-адреса одноадресной рассылки в. Если для элемента InterfaceLuid не задано значение (значение этого элемента было равно нулю), элемент InterfaceIndex будет использоваться для определения интерфейса.
Если элемент OnLinkPrefixLength структуры MIB_UNICASTIPADDRESS_ROW, к которому указывает параметр Row, имеет значение 255, CreateUnicastIpAddressEntry добавляет новый IP-адрес одноадресной рассылки с элементом OnLinkPrefixLength, равным длине IP-адреса. Поэтому для одноадресного IPv4-адреса для параметра OnLinkPrefixLength задано значение 32, а Для одноадресного IPv6-адреса для onLinkPrefixLength задано значение 128. Если этот параметр приведет к неправильной маске подсети для IPv4-адреса или неправильного префикса ссылки для IPv6-адреса, драйвер должен задать для элемента OnLinkPrefixLength правильное значение перед вызовом CreateUnicastIpAddressEntry.
Если IP-адрес одноадресной рассылки создается неправильно с помощью элемента OnLinkPrefixLength, драйвер может изменить IP-адрес, вызвав SetUnicastIpAddressEntry с элементом OnLinkPrefixLength, равным правильному значению.
Элементы DadState, ScopeId и CreateTimeStamp структуры MIB_UNICASTIPADDRESS_ROW, которые указывает на то, что параметр Row указывает на то, игнорируются при вызове функции CreateUnicastIpAddressEntry. Эти члены задаются сетевым стеком. Член ScopeId автоматически определяется интерфейсом, в который добавляется адрес.
Функция CreateUnicastIpAddressEntry завершается ошибкой, если IP-адрес одноадресной рассылки, переданный в элементе адреса структуры MIB_UNICASTIPADDRESS_ROW, что параметр Row указывает на дубликат существующего IP-адреса одноадресной рассылки в интерфейсе. Обратите внимание, что драйвер может добавить IP-адрес петли обратной связи только с помощью функции CreateUnicastIpAddressEntry .
Ip-адрес одноадресной рассылки, передаваемый в элементе адреса структуры MIB_UNICASTIPADDRESS_ROW, к которому указывает параметр Row , недоступен немедленно. IP-адрес доступен после успешного завершения процесса обнаружения повторяющихся адресов. Для завершения процесса обнаружения повторяющихся адресов может потребоваться несколько секунд, так как ip-пакеты должны быть отправлены, а потенциальные ответы должны ожидаться. Для IPv6 процесс обнаружения повторяющихся адресов обычно занимает около 1 секунды. Для IPv4 процесс обнаружения повторяющихся адресов обычно занимает около 3 секунд.
После вызова функции CreateUnicastIpAddressEntry драйвер может использовать следующие методы, чтобы определить, доступен ли IP-адрес:
Использование опроса и функции GetUnicastIpAddressEntry
После успешного возврата вызова функции CreateUnicastIpAddressEntry приостанавливается на 1–3 секунды (в зависимости от того, создается ли IPv6 или IPv4-адрес), чтобы разрешить время успешного завершения процесса обнаружения дублирования адресов. Затем вызовите GetUnicastIpAddressEntry , чтобы получить обновленную структуру MIB_UNICASTIPADDRESS_ROW и проверить значение члена DadState . Если для элемента DadState задано значение IpDadStatePreferred , IP-адрес теперь доступен. Если для элемента DadState задано значение IpDadStateTentative , обнаружение повторяющихся адресов еще не завершено. В этом случае вызовите функцию GetUnicastIpAddressEntry каждые 0,5 секунды, пока элемент DadState по-прежнему имеет значение IpDadStateTentative. Если значение элемента DadState возвращается с некоторым значением, кроме IpDadStatePreferred или IpDadStateTentative, обнаружение повторяющихся адресов завершилось ошибкой, а IP-адрес недоступен.Вызовите одну из вспомогательных функций уведомления IP NotificationXxx, чтобы настроить асинхронное уведомление при изменении адреса.
После успешного вызова функции CreateUnicastIpAddressEntry вызовите функцию NotifyUnicastIpAddressChange, чтобы зарегистрировать драйвер, чтобы получать уведомления об изменениях ip-адресов одноадресной рассылки IPv6 или IPv4 в зависимости от типа создаваемого IP-адреса. При получении уведомления для создаваемого IP-адреса вызовите функцию GetUnicastIpAddressEntry , чтобы получить член DadState . Если для элемента DadState задано значение IpDadStatePreferred , IP-адрес теперь доступен. Если для элемента DadState задано значение IpDadStateTentative , обнаружение повторяющихся адресов еще не завершено, и драйвер должен ожидать будущих уведомлений. Если значение элемента DadState возвращается с некоторым значением, кроме IpDadStatePreferred или IpDadStateTentative, обнаружение повторяющихся адресов завершилось ошибкой, а IP-адрес недоступен.Если во время процесса обнаружения повторяющихся адресов носитель отключается, а затем повторно подключается, процесс обнаружения повторяющихся адресов перезапускается. Поэтому время завершения процесса может увеличиться за рамки типичного 1 второго значения для IPv6 или 3 секунды для IPv4.
Требования
Целевая платформа |
Универсальный |
Версия |
Доступно в Windows Vista и более поздних версиях операционных систем Windows. |
Верхний колонтитул |
Netioapi.h (include Netioapi.h) |
Библиотека |
Netio.lib |
IRQL |
< DISPATCH_LEVEL |
См. также
InitializeUnicastIpAddressEntry