RtlIpv6StringToAddressA 函式 (ip2string.h)

發行項
01/27/2024

RtlIpv6StringToAddress 函式會將 IPv6 位址的字串表示轉換為二進位 IPv6 位址。

語法

NTSYSAPI NTSTATUS RtlIpv6StringToAddressA(
  [in]  PCSTR    S,
  [out] PCSTR    *Terminator,
  [out] in6_addr *Addr
);

參數

[in] S

緩衝區的指標，其中包含IPv6位址的 NULL終止字串表示。

[out] Terminator

參數，接收終止已轉換字串之字元的指標。呼叫端可以使用此功能，從字串擷取更多資訊。

[out] Addr

要儲存 IPv6 位址的二進位表示法的指標。

傳回值

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

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

傳回碼	Description
STATUS_INVALID_PARAMETER	無效的參數已傳遞至函式。如果 S 參數指向的字串未包含 IPv6 位址的適當字串表示，就會傳回此錯誤。此錯誤碼定義於 Ntstatus.h 頭檔中。
其他	使用 FormatMessage 取得傳回錯誤的訊息字串。

備註

RtlIpv6StringToAddress 函式可用來將 IPv6 位址的字串表示轉換為以網路順序傳回的 IPv6 位址， (位元組從左至右排序) 。

RtlIpv6StringToAddress 是一個便利函式，不需要載入 Windows Sockets DLL 才能存取 Windows Sockets 中提供的函式，以執行字元串到 IP 地址轉換。

S 參數所指向的字串必須以 IPv6 位址字串的格式表示。 IPv6 位址的基本字串表示是由以冒號分隔的8個十六進位數位所組成。連續零數位的字串可能會取代為雙冒號。 IPv6 位址的字串表示中只能有一個雙冒號。如果位址是 IPv4 相容位址、IPv4 對應 IPv6 位址或 ISATAP 位址，則最後 32 位可能會以 IPv4 樣式的 dotted-octet 表示法表示。如需詳細資訊，請參閱 IETF 所發佈的 RFC 5942 第 5 節。

成功時， 終止符 參數會指向終止已轉換字串的字元。這可讓應用程式傳遞包含和IP位址的字串，並將其他資訊傳遞給 RtlIpv6StringToAddress 函式，然後剖析其餘資訊。

注意某些格式錯誤的 IPv6 位址 (：：：，例如，) 開頭為有效的 IPv6 位址。 RtlIpv6StringToAddress 函式會傳回成功，並將 IPv6 位址的有效部分剖析為雙冒號 (：：) 。終止符接著會指向第三個冒號。若要驗證整個傳入字串是否為有效的 IPv6 位址，您必須確定終止符指向正確的字元。如果 S 參數只包含 IPv6 位址，則終止符應該指向字串結尾的 NULL 字元。

定義 UNICODE 或_UNICODE時， 會將 RtlIpv6StringToAddress 定義為 RtlIpv6StringToAddressW，這是此函式的 Unicode 版本。 S 和終止符參數會定義至 PCWSTR 資料類型。

未定義 UNICODE 和_UNICODE時， 會將 RtlIpv6StringToAddress 定義為 RtlIpv6StringToAddressA，這是此函式的 ANSI 版本。 S 和終止符參數會定義至 PCSTR 資料類型。

IN6_ADDR 結構定義於 In6addr.h 頭檔中。

包含 RtlIpv6StringToAddress 函式的匯入連結庫不包含在針對 Windows Vista 發行的 Microsoft Windows 軟體開發工具包 (SDK) 中。 RtlIpv6StringToAddress 函式包含在 Windows 驅動程式套件 (WDK) 的 Ntdll.lib 匯入連結庫中。應用程式也可以使用 GetModuleHandle 和 GetProcAddress 函式，從 Ntdll.dll 擷取函式指標，並呼叫此函式。

注意

ip2string.h 標頭會根據 UNICODE 預處理器常數的定義，將 RtlIpv6StringToAddress 定義為別名，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求


最低支援的用戶端	Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2008 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	ip2string.h (包含 Mstcpip.h、Ip2string.h)
程式庫	ntdll.lib
Dll	ntdll.dll