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 指標，則會傳回此錯誤。 Row 參數所指向之 MIB_UNICASTIPADDRESS_ROW 結構的 Address 成員未設定為有效的單播 IPv4 或 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堆棧，且在MIB_UNICASTIPADDRESS_ROW結構MIB_UNICASTIPADDRESS_ROW 結構 成員中 指定了 IPv4 位址，則會傳回此錯誤，或者如果本機計算機上沒有 IPv6 堆棧，且 位址 成員中指定了 IPv6 位址。 |
| ERROR_OBJECT_ALREADY_EXISTS | 物件已經存在。 如果 Address 成員 Row 參數指向的 MIB_UNICASTIPADDRESS_ROW 結構成員是 InterfaceLuid 或 InterfaceIn dex MIB_UNICASTIPADDRESS_ROW 成員所指定的介面上現有單播 IP 位址重複，就會傳回此錯誤。 |
| 其他 | 使用 FormatMessage 函式取得傳回錯誤的訊息字串。 |
言論
使用 InitializeUnicastIpAddressEntry 函式，以預設值初始化 MIB_UNICASTIPADDRESS_ROW 結構項目的成員。 然後，驅動程式可以變更其想要修改之MIB_UNICASTIPADDRESS_ROW專案中的成員，然後呼叫 CreateUnicastIpAddressEntry 函式。
在輸入時，驅動程式必須初始化 Row 參數指向的下列MIB_UNICASTIPADDRESS_ROW結構成員。
位址
設定為有效的單播 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。
如果使用 OnLinkPrefixLength 成員集來建立單播 IP 位址，您的驅動程式可以呼叫 SetUnicastIpAddressEntry，並將 OnLinkPrefixLength 成員設為正確的值來變更 IP 位址。
呼叫 createUnicastIpAddressEntry 函式 時，DadState、ScopeId和 CreationTimeStamp 成員MIB_UNICASTIPADDRESS_ROW 結構的成員。 這些成員是由網路堆疊所設定。 ScopeId 成員會自動由新增位址的介面決定。
CreateUnicastIpAddressEntry 函式會失敗，如果傳入 位址 結構MIB_UNICASTIPADDRESS_ROW結構成員的單播 IP 位址，Row 參數所指向的MIB_UNICASTIPADDRESS_ROW成員是介面上現有單播 IP 位址的重複專案。 請注意，您的驅動程式只能使用 CreateUnicastIpAddressEntry 函式，將回送 IP 位址新增至回送介面。
傳入 位址的單播 IP 位址 MIB_UNICASTIPADDRESS_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，則重複地址偵測尚未完成。 在此情況下，請每隔 0.5 秒再次呼叫 GetUnicastIpAddressEntry 函式，而 DadState 成員仍設定為 IpDadStateTentative。 如果 DadState 成員的值傳回，除了 IpDadStatePreferred 或 IpDadStateTentative 以外，重複的地址偵測失敗，而且 IP 位址無法使用。呼叫其中一個IP協助程式 NotifyXxx 通知函式，以在位址變更時設定異步通知
呼叫 CreateUnicastIpAddressEntry 函式成功之後，請呼叫 NotifyUnicastIpAddressChange 函式，以根據所建立的 IP 位址類型，註冊驅動程式以通知 IPv6 或 IPv4 單播 IP 位址的變更。 收到所建立IP位址的通知時，請呼叫 getUnicastIpAddressEntry 函式來擷取 DadState 成員。 如果 DadState 成員的值設定為 IpDadStatePreferred，則 IP 位址現在可供使用。 如果 DadState 成員的值設定為 IpDadStateTentative，則重複位址偵測尚未完成，且驅動程式必須等候未來的通知。 如果 DadState 成員的值傳回，除了 IpDadStatePreferred 或 IpDadStateTentative 以外，重複的地址偵測失敗，而且 IP 位址無法使用。如果在重複的位址偵測程式期間，媒體會中斷連線，然後重新連線，則會重新啟動重複的位址偵測程式。 因此完成程式的時間可能會超過 IPv6 的典型 1 秒值或 IPv4 的 3 秒值。
要求
目標平臺 |
通用 |
版本 |
可在 Windows Vista 和更新版本的 Windows作系統中使用。 |
頁眉 |
Netioapi.h （包括 Netioapi.h） |
圖書館 |
Netio.lib |
IRQL |
< DISPATCH_LEVEL |
另請參閱
InitializeUnicastIpAddressEntry