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 指標、Row 參數所指向之 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堆棧，而且在Row參數所指向之MIB_UNICASTIPADDRESS_ROW結構的Address成員中指定了IPv4位址，或如果本機計算機上沒有IPv6堆棧，且Address成員中指定了IPv6位址，則會傳回此錯誤。 |
| ERROR_OBJECT_ALREADY_EXISTS | 物件已經存在。 如果 Row 參數指向之 MIB_UNICASTIPADDRESS_ROW 結構的 Address 成員是MIB_UNICASTIPADDRESS_ROW之 InterfaceLuid 或 InterfaceIndex 成員所指定的介面上現有單播 IP 位址的重複專案，就會傳回此錯誤。 |
| 其他 | 使用 FormatMessage 函式來取得傳回錯誤的訊息字串。 |
備註
使用 InitializeUnicastIpAddressEntry 函式，以預設值初始化MIB_UNICASTIPADDRESS_ROW結構項目的成員。 然後，驅動程式可以變更其想要修改之MIB_UNICASTIPADDRESS_ROW專案中的成員，然後呼叫 CreateUnicastIpAddressEntry 函式。
在輸入時，驅動程式必須初始化 Row 參數指向之MIB_UNICASTIPADDRESS_ROW結構的下列成員。
地址
設定為有效的單播 IPv4 或 IPv6 位址和系列。InterfaceLuid 或 InterfaceIndex
這些成員會依照稍早所列的順序使用。 因此，如果 指定 InterfaceLuid ，則會使用此成員來判斷要新增單播 IP 位址的介面。 如果 InterfaceLuid 成員未設定任何值（此成員的值設定為零），則接下來會使用 InterfaceIndex 成員來判斷介面。
如果 Row 參數指向的 MIB_UNICASTIPADDRESS_ROW 結構 OnLinkPrefixLength 成員設為 255，CreateUnicastIpAddressEntry會新增新的單播 IP 位址，並將 OnLinkPrefixLength 成員設定為等於 IP 位址長度。 因此，針對單播 IPv4 位址， OnLinkPrefixLength 會設定為 32，而單播 IPv6 位址的 OnLinkPrefixLength 會設定為 128。 如果此設定會導致 IPv4 位址的子網掩碼不正確或 IPv6 位址的連結前置詞不正確，驅動程式應該先將 OnLinkPrefixLength 成員設定為正確的值，然後再呼叫 CreateUnicastIpAddressEntry。
如果使用 OnLinkPrefixLength 成員設定不正確建立單播 IP 位址，您的驅動程式可以呼叫 SetUnicastIpAddressEntry 並將 OnLinkPrefixLength 成員設定為正確的值，以變更 IP 位址。
呼叫 CreateUnicastIpAddressEntry 函式時，會忽略 Row 參數所指向之MIB_UNICASTIPADDRESS_ROW結構的 DadState、ScopeId 和 CreationTimeStamp 成員。 這些成員是由網路堆疊所設定。 ScopeId 成員會自動由新增位址的介面決定。
如果 Row參數指向之 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 成員的值 設定為 IpDadStatePreferred ，則 IP 位址現在可供使用。 如果 DadState 成員的值 設定為 IpDadStateTentative ，則重複的位址偵測尚未完成。 在此情況下，當 DadState 成員仍設定為 IpDadStateTentative 時，每隔 0.5 秒再次呼叫 GetUnicastIpAddressEntry 函式。 如果 DadState 成員的值傳回的值為 IpDadStatePreferred 或 IpDadStateTentative 以外的某些值，則重複的位址偵測失敗，且 IP 位址無法使用。呼叫其中一個IP協助程式 NotifyXxx 通知函式，以設定地址變更時的異步通知
成功傳回 CreateUnicastIpAddressEntry 函式之後，請呼叫 NotifyUnicastIpAddressChange 函式，以註冊驅動程式，以通知 IPv6 或 IPv4 單播 IP 位址的變更，視所建立的 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