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	UTF8StringDestination和UTF8StringActualByteCount的兩個指標都是Null。
STATUS_INVALID_PARAMETER_4	UnicodeStringSource為Null。
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