SetUnicastIpAddressEntry 函数

项目
06/15/2023

SetUnicastIpAddressEntry 函数设置本地计算机上现有单播 IP 地址条目的属性。

语法

NETIOAPI_API SetUnicastIpAddressEntry(
  _In_ const MIB_UNICASTIPADDRESS_ROW *Row
);

参数

行 [in]
指向现有单播 IP 地址条目 的MIB_UNICASTIPADDRESS_ROW 结构条目的指针。

返回值

如果函数成功，SetUnicastIpAddressEntry 将返回STATUS_SUCCESS。

如果函数失败， SetUnicastIpAddressEntry 将返回以下错误代码之一：

返回代码	说明
STATUS_INVALID_PARAMETER	向该函数传递了无效参数。如果在 Row 参数中传递 NULL 指针，Row 参数指向的 MIB_UNICASTIPADDRESS_ROW 结构的 Address 成员未设置为有效的单播 IPv4 或 IPv6 地址，或者未指定 MIB_UNICASTIPADDRESS_ROW 结构的 InterfaceLuid 和 InterfaceIndex 成员，则返回此错误。
STATUS_NOT_FOUND	找不到指定的接口。如果函数找不到 Row 参数指向的 MIB_UNICASTIPADDRESS_ROW 结构的 InterfaceLuid 或 InterfaceIndex 成员指定的网络接口，则返回此错误。
STATUS_NOT_SUPPORTED	不支持该请求。如果本地计算机上没有 IPv4 堆栈，并且 Row 参数指向的 MIB_UNICASTIPADDRESS_ROW 结构的 Address 成员中指定了 IPv4 地址，或者本地计算机上没有 IPv6 堆栈，并且 Address 成员中指定了 IPv6 地址，则返回此错误。
其他	使用 FormatMessage 函数获取返回错误的消息字符串。

注解

GetUnicastIpAddressEntry 函数通常用于检索要修改的现有MIB_UNICASTIPADDRESS_ROW结构条目。然后，驱动程序可以更改要修改的MIB_UNICASTIPADDRESS_ROW条目中的成员，然后调用 SetUnicastIpAddressEntry 函数。

在进行更改之前，驱动程序可以调用 InitializeUnicastIpAddressEntry 函数，以使用默认值初始化MIB_UNICASTIPADDRESS_ROW结构条目的成员。但是，驱动程序通常会在调用 InitializeUnicastIpAddressEntry 之前保存 InterfaceLuid 或 InterfaceIndex 成员，并在调用后还原其中一个成员。

驱动程序必须初始化 Row 参数指向的 MIB_UNICASTIPADDRESS_ROW 结构的以下成员。

Address
设置为有效的单播 IPv4 或 IPv6 地址和系列。
InterfaceLuid 或 InterfaceIndex
这些成员按前面列出的顺序使用。因此，如果指定 了 InterfaceLuid ，则此成员用于确定接口。如果没有为 InterfaceLuid 成员设置值 (此成员的值设置为零) ，则接下来使用 InterfaceIndex 成员来确定接口。

如果 Row 参数指向的 MIB_UNICASTIPADDRESS_ROW 结构的 OnLinkPrefixLength 成员设置为 255，则 SetUnicastIpAddressEntry 将设置单播 IP 地址属性，以便 OnLinkPrefixLength 成员等于 IP 地址的长度。对于单播 IPv4 地址， OnLinkPrefixLength 设置为 32。对于单播 IPv6 地址， OnLinkPrefixLength 设置为 128。如果这些设置会导致 IPv4 地址的子网掩码不正确或 IPv6 地址的链接前缀不正确，驱动程序应在调用 SetUnicastIpAddressEntry 之前将此成员设置为正确的值。

SetUnicastIpAddressEntry 忽略 Row 参数指向的 MIB_UNICASTIPADDRESS_ROW 结构的 DadState、ScopeId 和 CreationTimeStamp 成员。这些成员由网络堆栈设置，无法使用 SetUnicastIpAddressEntry 函数进行更改。 ScopeId 成员由添加地址的接口自动确定。

要求

目标平台	通用
版本	在 Windows Vista 和更高版本的 Windows 操作系统中可用。
标头	Netioapi.h (包括 Netioapi.h)
库	Netio.lib
IRQL	< DISPATCH_LEVEL