RtlIpv4AddressToStringExW 函式 (ip2string.h)

發行項
02/28/2024

RtlIpv4AddressToStringEx 函式會將 IPv4 位址和埠號碼轉換為因特網標準格式的字串。

語法

NTSYSAPI NTSTATUS RtlIpv4AddressToStringExW(
  [in]      const in_addr *Address,
  [in]      USHORT        Port,
  [out]     PWSTR         AddressString,
  [in, out] PULONG        AddressStringLength
);

參數

[in] Address

以網路位元組順序排列的IPv4位址。

[in] Port

網路位元組順序格式的埠號碼。這是選擇性參數。

[out] AddressString

緩衝區的指標，可接收IPv4位址和埠的 NULL終止字串表示。此緩衝區的大小應該足以保存至少INET_ADDRSTRLEN個字元。 INET_ADDRSTRLEN值定義於 Ws2ipdef.h 頭檔中。

[in, out] AddressStringLength

在輸入時，符合 AddressString 參數所指向之緩衝區中的字元數，包括 NULL 終止符。在輸出時，此參數包含實際寫入 AddressString 參數所指向之緩衝區的字元數。

傳回值

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

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

傳回碼	Description
STATUS_INVALID_PARAMETER	無效的參數已傳遞至函式。如果在 AddressString 或 AddressStringLength 參數中傳遞 NULL 指標，就會傳回此錯誤。如果 AddressString 參數所指向的緩衝區長度不足以接收 IPv4 位址和埠的字串表示，也會傳回此錯誤。
其他	使用 FormatMessage 取得傳回錯誤的訊息字串。

備註

RtlIpv4AddressToStringEx 函式可用來將 IPv4 位址和埠號碼轉換成以因特網點十進位格式表示 IPv4 位址的字串表示，後面接著冒號字元和埠的字元串表示。

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

如果 AddressString 參數所指向的緩衝區長度不夠大，無法接收 IPv4 位址和埠的字串表示， RtlIpv4AddressToStringEx 會傳回 ERROR_INVALID_PARAMETER ，並將 AddressStringLength 參數設定為所需的緩衝區長度。

定義 UNICODE 或_UNICODE時， RtlIpv4AddressToStringEx 會定義為 RtlIpv4AddressToStringExW，此函式的 Unicode 版本。 AddressString 參數會定義至 PWSTR 數據類型。

未定義 UNICODE 和_UNICODE時， RtlIpv4AddressToStringEx 會定義為 RtlIpv4AddressToStringExA，此函式的 ANSI 版本。 AddressString 參數會定義為 PSTR 數據類型。

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

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

規格需求

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