SetUnicastIpAddressEntry 函数 (netioapi.h)
SetUnicastIpAddressEntry 函数设置本地计算机上现有单播 IP 地址条目的属性。
语法
IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetUnicastIpAddressEntry(
[in] const MIB_UNICASTIPADDRESS_ROW *Row
);
参数
[in] Row
指向现有单播 IP 地址条目 的MIB_UNICASTIPADDRESS_ROW 结构条目的指针。
返回值
如果函数成功，则返回值NO_ERROR。
如果函数失败，则返回值为以下错误代码之一。
| 返回代码 | 说明 |
|---|---|
|
访问被拒绝。 此错误在以下几种情况下返回：用户在本地计算机上缺少所需的管理权限，或者应用程序没有作为内置管理员 (RunAs 管理员) 在增强的 shell 中运行。 |
|
向该函数传递了无效参数。 如果在 Row 参数中传递 NULL 指针，Row 参数指向MIB_UNICASTIPADDRESS_ROW的 Address 成员未设置为有效的单播 IPv4 或 IPv6 地址，或者 Row 参数指向的MIB_UNICASTIPADDRESS_ROW的 InterfaceLuid 或 InterfaceIndex 成员均未指定，则返回此错误。
对于为 MIB_UNICASTIPADDRESS_ROW 结构中的成员设置的值中的其他错误，也会返回此错误。 这些错误包括以下错误：如果 ValidLifetime 成员小于 PreferredLifetime 成员，如果 PrefixOrigin 成员设置为 IpPrefixOriginUnchanged，SuffixOrigin 未设置为 IpSuffixOriginUnchanged，如果 PrefixOrigin 成员未设置为 IpPrefixOriginUnchanged，并且 SuffixOrigin 设置为 IpSuffixOriginUnchanged，如果 PrefixOrigin如果 SuffixOrigin 成员未设置为 NL_SUFFIX_ORIGIN 枚举中的值，或者如果 OnLinkPrefixLength 成员设置为大于 IP 地址长度的值，则不会将 member 设置为 NL_PREFIX_ORIGIN 枚举中的值，对于单播 IPv4 地址，以位 (32 或 128 表示单播 IPv6 地址) 。 |
|
找不到指定的接口。 如果找不到由 Row 参数指向的MIB_UNICASTIPADDRESS_ROW的 InterfaceLuid 或 InterfaceIndex 成员指定的网络接口，则返回此错误。 |
|
不支持该请求。 如果本地计算机上没有 IPv4 堆栈，且在 Row 参数指向的 Address 成员MIB_UNICASTIPADDRESS_ROW指定了 IPv4 地址，或者本地计算机上没有 IPv6 堆栈，并且地址成员中指定了 IPv6 地址，则返回此错误。 |
|
使用 FormatMessage 获取返回错误的消息字符串。 |
注解
SetUnicastIpAddressEntry 函数在 Windows Vista 及更高版本上定义。
GetUnicastIpAddressEntry 函数通常用于检索要修改的现有MIB_UNICASTIPADDRESS_ROW结构条目。 然后，应用程序可以更改要修改 的MIB_UNICASTIPADDRESS_ROW 条目中的成员，然后调用 SetUnicastIpAddressEntry 函数。
应用程序可以调用 InitializeUnicastIpAddressEntry 函数，以在进行更改之前使用默认值初始化 MIB_UNICASTIPADDRESS_ROW 结构条目的成员。 但是，应用程序通常会在调用 InitializeUnicastIpAddressEntry 之前保存 InterfaceLuid 或 InterfaceIndex 成员，并在调用后还原其中一个成员。
Row 参数指向的MIB_UNICASTIPADDRESS_ROW结构中的 Address 成员必须初始化为有效的单播 IPv4 或 IPv6 地址和系列。 此外，必须初始化指向 Row 参数的 MIB_UNICASTIPADDRESS_ROW 结构中的以下至少一个成员：InterfaceLuid 或 InterfaceIndex。
字段按上面列出的顺序使用。 因此，如果指定 了 InterfaceLuid ，则使用此成员来确定接口。 如果没有为 InterfaceLuid 成员设置值， (此成员的值) 设置为零，则接下来使用 InterfaceIndex 成员来确定接口。
如果 Row 参数指向的 MIB_UNICASTIPADDRESS_ROWOnLinkPrefixLength 成员设置为 255，则 SetUnicastIpAddressEntry 将设置单播 IP 地址属性，以便 OnLinkPrefixLength 成员等于 IP 地址的长度。 因此，对于单播 IPv4 地址，对于单播 IPv6 地址， OnLinkPrefixLength 设置为 32，OnLinkPrefixLength 设置为 128。 如果这会导致 IPv4 地址的子网掩码不正确或 IPv6 地址的链接前缀不正确，则在调用 SetUnicastIpAddressEntry 之前，应用程序应将此成员设置为正确的值。
调用 SetUnicastIpAddressEntry 函数时，将忽略行指向的 MIB_UNICASTIPADDRESS_ROW 结构的 DadState、ScopeId 和 CreationTimeStamp 成员。 这些成员由网络堆栈设置，不能使用 SetUnicastIpAddressEntry 函数进行更改。 ScopeId 成员由添加地址的接口自动确定。
SetUnicastIpAddressEntry 函数只能由以管理员组成员身份登录的用户调用。 如果 SetUnicastIpAddressEntry 由不是 Administrators 组成员的用户调用，则函数调用将失败并返回 ERROR_ACCESS_DENIED 。
SetUnicastIpAddressEntry 函数也可能因为 Windows Vista 及更高版本上的用户帐户控制 (UAC) 而失败。 如果包含此函数的应用程序由以管理员组成员身份登录（而非内置管理员）的用户执行，则此调用将失败，除非应用程序已在清单文件中标记为 requestedExecutionLevel 设置为 requireAdministrator。 如果应用程序缺少此清单文件，则作为管理员组成员（而非内置管理员）登录的用户必须在增强的 shell 中执行应用程序，因为内置管理员 (RunAs 管理员) 才能使此功能成功。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows Vista [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2008 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | netioapi.h (包括 Iphlpapi.h) |
| Library | Iphlpapi.lib |
| DLL | Iphlpapi.dll |