共用方式為


RtlUnicodeToUTF8N 函式

使用 8 位 Unicode 轉換格式 (UTF-8) 字碼頁,將指定的 Unicode 字串轉譯成新的字元字串。

語法

NTSTATUS WINAPI RtlUnicodeToUTF8N(
  _Out_     PCHAR  UTF8StringDestination,
  _In_      ULONG  UTF8StringMaxByteCount,
  _Out_opt_ PULONG UTF8StringActualByteCount,
  _In_      PCWSTR UnicodeStringSource,
  _In_      ULONG  UnicodeStringByteCount
);

參數

UTF8StringDestination [out]

呼叫端配置緩衝區的指標,用來接收已翻譯的字串。

UTF8StringMaxByteCount [in]

要寫入 UTF8StringDestination的最大位元組數目。 如果此值導致截斷翻譯的字串, RtlUnicodeToUTF8N 會傳回錯誤狀態。

UTF8StringActualByteCount [out, optional]

呼叫端配置的變數指標,接收已翻譯字串的長度,以位元組為單位。 這個參數是選擇性的,而且可以是 Null。 如果字串被截斷,則傳回的數位會計算實際的截斷字串計數。

UnicodeStringSource [in]

要翻譯之 Unicode 來源字串的指標。

*UnicodeStringByteCount * [in]

指定 UnicodeStringSource 參數指向之 Unicode 來源字串中的位元組數目。

傳回值

RtlUnicodeToUTF8N 會傳回下列其中一個 NTSTATUS 值:

傳回碼 描述
STATUS_SUCCESS
Unicode 字串已轉換為 UTF-8。
STATUS_SOME_NOT_MAPPED
遇到不正確輸入字元並加以取代。 此狀態會被視為成功狀態。
STATUS_INVALID_PARAMETER
UTF8StringDestinationUTF8StringActualByteCount的兩個指標都是Null
STATUS_INVALID_PARAMETER_4
UnicodeStringSourceNull
STATUS_BUFFER_TOO_SMALL
UTF8StringDestination 已截斷。

 

備註

雖然 UTF8StringActualByteCount 是選擇性的,而且可以是 Null,但呼叫端應該為它提供儲存體,因為接收的長度可用來判斷轉換是否成功。 這個常式不會修改來源字串。 如果指定的 UnicodeStringSource 包含 Null 結束字元,而且指定的 UTF8StringMaxByteCount 未造成截斷,則會傳回 Null 終止 UTF-8 字串。

如果輸出遭到截斷,而且遇到不正確輸入字元,則函式會傳回STATUS_BUFFER_TOO_SMALL錯誤。

如果 UTF8StringDestination 設定為 Null ,函式會傳回必要的位元組數目來裝載已翻譯的字串,而 不需要 UTF8StringActualByteCount中的任何截斷。

RtlUnicodeToUTF8N的呼叫端必須在 IRQL < DISPATCH_LEVEL上執行。

規格需求

需求
最低支援的用戶端
Windows 7 [僅限傳統型應用程式]
最低支援的伺服器
Windows Server 2008 R2 [僅限桌面應用程式]
標頭
Wdm.h
DLL
Ntdll.dll

另請參閱

RtlUTF8ToUnicodeN