RtlIpv4StringToAddressA 函式 (ip2string.h)

發行項
01/27/2024

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

語法

NTSYSAPI NTSTATUS RtlIpv4StringToAddressA(
  [in]  PCSTR   S,
  [in]  BOOLEAN Strict,
  [out] PCSTR   *Terminator,
  [out] in_addr *Addr
);

參數

[in] S

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

[in] Strict

值，指出字串是否必須是以嚴格四部分點十進位表示法表示的IPv4位址。如果此參數為 TRUE，字串必須以虛線-十進位數加上四個部分。如果此參數為 FALSE，則允許四個可能窗體的任一種，具有十進位、八進位或十六進位表示法。如需詳細資訊，請參閱＜備註＞一節。

[out] Terminator

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

[out] Addr

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

傳回值

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

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

傳回碼	Description
STATUS_INVALID_PARAMETER	無效的參數已傳遞至函式。如果 Strict 參數設定為 TRUE，但 S 參數所指向的字串未包含 IPv4 位址的四部分虛線十進位字串表示，則會傳回此錯誤。如果 S 參數指向的字串未包含 IPv4 位址的適當字串表示，也會傳回此錯誤。此錯誤碼定義於 Ntstatus.h 頭檔中。
其他	使用 FormatMessage 取得傳回錯誤的訊息字串。

備註

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

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

如果 Strict 參數設定為 TRUE， 則 S 參數所指向的字串必須以嚴格的虛點十進位表示法表示法表示。此嚴格格式需要指定四個部分。每個部分都會解譯為數據的小數位節，並從左至右指派給IPv4位址的四個字節。

當 Strict 參數設定為 FALSE 時， S 參數所指向的字串可以是數種可能格式的任何一種。當 S 參數指向的緩衝區包含三部分的位址字串時，最後一個部分會解譯為 16 位的數量，並放在最右邊的網路位址兩個字節中。這讓三部分位址格式方便將類別 B 網络位址指定為「128.net.host」。。當 S 參數指向的緩衝區包含兩部分位址字串時，最後一個部分會解譯為 24 位數量，並放在網路位址最右邊的三個字節中。這可讓兩部分位址格式方便將類別 A 網路位址指定為「net.host」。。當 S 參數指向的緩衝區只包含一部分的位址字串時，此值會直接儲存在網路位址中，而不需要重新排列任何位元組。

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

定義 UNICODE 或_UNICODE時， RtlIpv4StringToAddress 會定義為 RtlIpv4StringToAddressW，此函式的 Unicode 版本。 S 參數會定義為 PCWSTR 資料類型，而終止符參數會定義為 LPCWSTR 數據類型。

未定義 UNICODE 和_UNICODE時， RtlIpv4StringToAddress 會定義為 RtlIpv4StringToAddressA，此函式的 ANSI 版本。 S 和終止符參數會定義為 PCSTR 資料類型。

IN_ADDR 結構定義於 Inaddr.h 頭檔中。

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

注意

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

規格需求


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