setUnicastIpAddressEntry 函式 (netioapi.h)

發行項
02/01/2024

SetUnicastIpAddressEntry 函式會在本機計算機上設定現有單播IP位址專案的屬性。

語法

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetUnicastIpAddressEntry(
  [in] const MIB_UNICASTIPADDRESS_ROW *Row
);

參數

[in] Row

現有單播IP位址專案的 MIB_UNICASTIPADDRESS_ROW 結構專案的指標。

傳回值

如果函式成功，傳回值會NO_ERROR。

如果函式失敗，傳回值就是下列其中一個錯誤碼。

傳回碼	Description
ERROR_ACCESS_DENIED	存取遭到拒絕。此錯誤會在下列幾個情況下傳回：使用者缺少本機計算機上的必要系統管理許可權，或應用程式未在增強的殼層中執行，因為 RunAs 系統管理員) 內建系統管理員 (。
ERROR_INVALID_PARAMETER	無效的參數已傳遞至函式。如果在 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，則為 PrefixOriginUnchanged成員不會設定為來自NL_PREFIX_ORIGIN列舉的值，如果 SuffixOrigin 成員未設定為來自NL_SUFFIX_ORIGIN列舉的值，或 OnLinkPrefixLength 成員設定為大於 IP 位址長度的值，則位 (32 表示單播 IPv4 位址，或單播 IPv6 位址為 128) 。
ERROR_NOT_FOUND	找不到指定的介面。如果找不到 Row 參數所指向MIB_UNICASTIPADDRESS_ROW之 InterfaceLuid 或 InterfaceIndex 成員所指定的網路介面，就會傳回此錯誤。
ERROR_NOT_SUPPORTED	不支援此要求。如果本機計算機上沒有IPv4堆棧，而且在Row參數所指向的Address成員MIB_UNICASTIPADDRESS_ROW指定IPv4位址，或本機電腦上沒有IPv6堆棧，且在Address成員中指定了IPv6位址，則會傳回此錯誤。
其他	使用 FormatMessage 取得傳回錯誤的訊息字串。

備註

SetUnicastIpAddressEntry 函式是在 Windows Vista 和更新版本上定義。

GetUnicastIpAddressEntry 函式通常用來擷取要修改的現有MIB_UNICASTIPADDRESS_ROW結構專案。然後，應用程式可以變更想要修改 之MIB_UNICASTIPADDRESS_ROW 專案中的成員，然後呼叫 SetUnicastIpAddressEntry 函式。

應用程式可以呼叫 InitializeUnicastIpAddressEntry 函式，先使用預設值初始化 MIB_UNICASTIPADDRESS_ROW 結構項目的成員，再進行變更。不過，應用程式通常會先儲存 InterfaceLuid 或 InterfaceIndex 成員，再呼叫 InitializeUnicastIpAddressEntry ，並在呼叫之後還原其中一個成員。

Row 參數所指向之MIB_UNICASTIPADDRESS_ROW結構中的 Address 成員必須初始化為有效的單播 IPv4 或 IPv6 位址和系列。此外，至少必須初始化指向 Row 參數之MIB_UNICASTIPADDRESS_ROW結構中的下列其中一個成員：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 成員會自動由新增位址的介面決定。

SetUnicastIpAddressEntry 函式只能由以 Administrators 群組成員身分登入的使用者呼叫。如果 SetUnicastIpAddressEntry 是由不是 Administrators 群組成員的使用者呼叫，則函數調用將會失敗，並 傳回ERROR_ACCESS_DENIED 。

SetUnicastIpAddressEntry 函式也可能因為使用者帳戶控制 (Windows Vista 和更新版本上的 UAC) 而失敗。如果包含此函式的應用程式是由以內建系統管理員以外的 Administrators 群組成員身分登入的使用者所執行，除非應用程式已在指令清單檔案中標示 為 requestedExecutionLevel 設定為 requireAdministrator，否則此呼叫將會失敗。如果應用程式缺少此指令清單檔，則以系統管理員以外的 Administrators 群組成員身分登入的使用者，必須在增強的殼層中執行應用程式，因為內建的 Administrator (RunAs 系統管理員) ，此函式才能成功。

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	netioapi.h (包含 Iphlpapi.h)
程式庫	Iphlpapi.lib
Dll	Iphlpapi.dll