CreateUnicastIpAddressEntry 函数
CreateUnicastIpAddressEntry 函数在本地计算机上添加新的单播 IP 地址条目。
语法
NETIOAPI_API CreateUnicastIpAddressEntry(
_In_ const MIB_UNICASTIPADDRESS_ROW *Row
);
参数
- 行 [in]
指向单播 IP 地址条目的MIB_UNICASTIPADDRESS_ROW结构条目的指针。
返回值
如果函数成功，CreateUnicastIpAddressEntry 将返回STATUS_SUCCESS。
如果函数失败， CreateUnicastIpAddressEntry 将返回以下错误代码之一：
| 返回代码 | 说明 |
|---|---|
| STATUS_INVALID_PARAMETER | 传递给函数的参数无效。 如果在 Row 参数中传递 NULL 指针、行参数指向的 MIB_UNICASTIPADDRESS_ROW 结构的 Address 成员未设置为有效的单播 IPv4 或 IPv6 地址，或者未指定MIB_UNICASTIPADDRESS_ROW结构的 InterfaceLuid 和 InterfaceIndex 成员，则返回此错误。 对于为MIB_UNICASTIPADDRESS_ROW结构中的成员设置的值中的其他错误，也会返回此错误。 这些错误包括以下情况：
有关NL_PREFIX_ORIGIN和NL_SUFFIX_ORIGIN枚举的可能值，请参阅 MIB_UNICASTIPADDRESS_ROW。 |
| STATUS_NOT_FOUND | 无法找到指定的接口。 如果函数找不到由 Row 参数指向的 MIB_UNICASTIPADDRESS_ROW 结构的 InterfaceLuid 或 InterfaceIndex 成员指定的网络接口，则返回此错误。 |
| STATUS_NOT_SUPPORTED | 不支持该请求。 如果没有 IPv4 堆栈位于本地计算机上，并且行参数指向的 MIB_UNICASTIPADDRESS_ROW 结构的地址成员中指定了 IPv4 地址，或者本地计算机上没有 IPv6 堆栈，并且地址成员中指定了 IPv6 地址，则返回此错误。 |
| ERROR_OBJECT_ALREADY_EXISTS | 对象已存在。 如果行参数指向的 MIB_UNICASTIPADDRESS_ROW 结构的 Address 成员是MIB_UNICASTIPADDRESS_ROW的 InterfaceLuid 或 InterfaceIndex 成员指定的接口上现有单播 IP 地址的副本，则返回此错误。 |
| 其他 | 使用 FormatMessage 函数获取返回的错误的消息字符串。 |
注解
使用 InitializeUnicastIpAddressEntry 函数使用默认值初始化MIB_UNICASTIPADDRESS_ROW结构条目的成员。 然后，驱动程序可以更改要修改的MIB_UNICASTIPADDRESS_ROW条目中的成员，然后调用 CreateUnicastIpAddressEntry 函数。
在输入时，驱动程序必须初始化 Row 参数指向的MIB_UNICASTIPADDRESS_ROW结构的以下成员。
Address
设置为有效的单播 IPv4 或 IPv6 地址和系列。InterfaceLuid 或 InterfaceIndex
这些成员按前面列出的顺序使用。 因此，如果 指定 InterfaceLuid ，则此成员用于确定要向其添加单播 IP 地址的接口。 如果未为 InterfaceLuid 成员设置任何值（此成员的值设置为零），则接下来使用 InterfaceIndex 成员来确定接口。
如果 Row 参数指向的 MIB_UNICASTIPADDRESS_ROW 结构的 OnLinkPrefixLength 成员设置为 255，CreateUnicastIpAddressEntry 会添加新的单播 IP 地址，并将 OnLinkPrefixLength 成员设置为等于 IP 地址的长度。 因此，对于单播 IPv4 地址，OnLinkPrefixLength 设置为 32，OnLinkPrefixLength 设置为单播 IPv6 地址的 128。 如果此设置会导致 IPv4 地址的子网掩码不正确或 IPv6 地址的链接前缀不正确，驱动程序应在调用 CreateUnicastIpAddressEntry 之前将 OnLinkPrefixLength 成员设置为正确的值。
如果使用未正确设置 OnLinkPrefixLength 成员创建单播 IP 地址，驱动程序可以通过调用 SetUnicastIpAddressEntry 并将 OnLinkPrefixLength 成员设置为正确的值来更改 IP 地址。
调用 CreateUnicastIpAddressEntry 函数时，Row 参数指向的 MIB_UNICASTIPADDRESS_ROW 结构的 DadState、ScopeId 和 CreationTimeStamp 成员将被忽略。 这些成员由网络堆栈设置。 ScopeId 成员由添加地址的接口自动确定。
如果行参数指向的 MIB_UNICASTIPADDRESS_ROW 结构的地址成员中传递的单播 IP 地址是接口上现有单播 IP 地址的副本，则 CreateUnicastIpAddressEntry 函数将失败。 请注意，驱动程序只能使用 CreateUnicastIpAddressEntry 函数将环回 IP 地址添加到环回接口。
在 row 参数指向的 MIB_UNICASTIPADDRESS_ROW 结构的 Address 成员中传递的单播 IP 地址不能立即使用。 重复地址检测过程成功完成后，IP 地址可用。 重复地址检测过程可能需要几秒钟才能完成，因为必须发送 IP 数据包，并且必须等待潜在的响应。 对于 IPv6，重复地址检测过程通常需要大约 1 秒。 对于 IPv4，重复的地址检测过程通常需要大约 3 秒。
驱动程序调用 CreateUnicastIpAddressEntry 函数后，可以使用以下方法来确定 IP 地址是否仍然可用：
使用轮询和 GetUnicastIpAddressEntry 函数
成功调用 CreateUnicastIpAddressEntry 函数后，暂停 1 到 3 秒（具体取决于正在创建 IPv6 或 IPv4 地址），以允许成功完成重复地址检测过程的时间。 然后，调用 GetUnicastIpAddressEntry 以检索更新MIB_UNICASTIPADDRESS_ROW结构并检查 DadState 成员的值。 如果 DadState 成员的值设置为 IpDadStateP 引用，则 IP 地址现在可用。 如果 DadState 成员的值设置为 IpDadStateTentative，则重复地址检测尚未完成。 在这种情况下，每隔 0.5 秒再次调用 GetUnicastIpAddressEntry 函数，而 DadState 成员仍设置为 IpDadStateTentative。 如果 DadState 成员的值返回的值为 IpDadStateP 引用或 IpDadStateTentative 以外的某些值，则重复地址检测失败，并且 IP 地址不可用。调用其中一个 IP 帮助程序 NotifyXxx 通知函数来设置地址更改时的异步通知
成功调用 CreateUnicastIpAddressEntry 函数后，调用 NotifyUnicastIpAddressChange 函数以注册驱动程序以通知对 IPv6 或 IPv4 单播 IP 地址的更改，具体取决于正在创建的 IP 地址的类型。 收到正在创建的 IP 地址的通知时，请调用 GetUnicastIpAddressEntry 函数以检索 DadState 成员。 如果 DadState 成员的值设置为 IpDadStateP 引用，则 IP 地址现在可用。 如果 DadState 成员的值设置为 IpDadStateTentative，则重复地址检测尚未完成，并且驱动程序必须等待将来的通知。 如果 DadState 成员的值返回的值为 IpDadStateP 引用或 IpDadStateTentative 以外的某些值，则重复地址检测失败，并且 IP 地址不可用。如果在重复地址检测过程中，媒体断开连接，然后重新连接，则会重启重复的地址检测过程。 因此，完成此过程的时间可能会超过 IPv6 的典型 1 秒值或 IPv4 的 3 秒值。
要求
目标平台 |
通用 |
版本 |
在 Windows Vista 及更高版本的 Windows 操作系统中可用。 |
头文件 |
Netioapi.h（包括 Netioapi.h） |
库 |
Netio.lib |
IRQL |
< DISPATCH_LEVEL |
另请参阅
InitializeUnicastIpAddressEntry
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈