RtlIpv6StringToAddressExW 函式 (ip2string.h)

發行項
03/05/2024

RtlIpv6StringToAddressEx 函式會將 IPv6 位址、範圍標識碼和埠號碼的字串表示轉換為二進位 IPv6 位址、範圍標識碼和埠。

語法

NTSYSAPI NTSTATUS RtlIpv6StringToAddressExW(
  [in]  PCWSTR   AddressString,
  [out] in6_addr *Address,
  [out] PULONG   ScopeId,
  [out] PUSHORT  Port
);

參數

[in] AddressString

緩衝區的指標，其中包含IPv6位址、範圍標識符和埠號碼的 NULL終止字串表示。

[out] Address

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

[out] ScopeId

IPv6 位址範圍標識碼儲存位置的指標。如果 AddressString 參數不包含範圍標識碼的字串表示法，則會在此參數中傳回零。

[out] Port

儲存埠號碼的指標。埠號碼是網路位元組順序格式。如果 AddressString 參數未包含埠號碼的字串表示法，則會在此參數中傳回零。

傳回值

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

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

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

備註

RtlIpv6StringToAddressEx 函式可用來將 IPv6 位址、範圍標識碼和埠號碼的字串表示轉換為二進位 IPv6 位址、範圍標識符和埠號碼。 IPv6 位址會以網路順序傳回， (位元組從左至右排序) 。埠號碼和範圍標識碼會依網路順序傳回。

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

AddressString 參數所指向的字串必須以 IPv6 位址字串的格式表示，後面接著選擇性的百分比字元和範圍標識符字串。 IPv6 位址和範圍標識符字串必須以方括弧括住。 IPv6 位址和範圍標識符字串後面的右方括號後面可能會加上選擇性冒號和埠號碼的字串表示。 IPv6 位址的基本字串表示是由以冒號分隔的8個十六進位數位所組成。連續零數位的字串可能會取代為雙冒號。 IPv6 位址的字串表示中只能有一個雙冒號。如果位址是 IPv4 相容位址、IPv4 對應 IPv6 位址或 ISATAP 位址，則最後 32 位可能會以 IPv4 樣式的 dotted-octet 表示法表示。如需詳細資訊，請參閱 IETF 所發佈的 RFC 5942 第 5 節。

定義 UNICODE 或_UNICODE時， 會將 RtlIpv6StringToAddressEx 定義為 RtlIpv6StringToAddressExW，這是此函式的 Unicode 版本。 AddressString 參數會定義為PCWSTR數據類型。

未定義 UNICODE 和_UNICODE時， 會將 RtlIpv6StringToAddressEx 定義為 RtlIpv6StringToAddressExA，這是此函式的 ANSI 版本。 AddressString 參數會定義為 PCSTR 數據類型。

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

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

規格需求

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