RtlUTF8ToUnicodeN 函式

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

語法

NTSTATUS WINAPI RtlUTF8ToUnicodeN(
  _Out_     PWSTR  UnicodeStringDestination,
  _In_      ULONG  UnicodeStringMaxByteCount,
  _Out_opt_ PULONG UnicodeStringActualByteCount,
  _In_      PCCH   UTF8StringSource,
  _In_      ULONG  UTF8StringByteCount
);

參數

UnicodeStringDestination [out]

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

UnicodeStringMaxByteCount [in]

在 UnicodeStringDestination寫入的最大位元組數目。 如果此值導致截斷翻譯的字串， RtlUTF8ToUnicodeN 會傳回錯誤狀態。

UnicodeStringActualByteCount [out， optional]

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

UTF8StringSource [in]

要翻譯之字串的指標。

UTF8StringByteCount [in]

UTF8StringSource字串的大小，以位元組為單位。

傳回值

RtlUTF8ToUnicodeN 會傳回下列其中一個 NTSTATUS 值：

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

 

備註

雖然 UnicodeStringActualByteCount 是選擇性的，而且可以是 Null，但呼叫端應該為它提供儲存體，因為接收的長度可用來判斷轉換是否成功。

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

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

除非UnicodeStringDestination和UTF8StringSource指標相等，否則 RtlUTF8ToUnicodeN不會修改來源字串。 傳回的 Unicode 字串不是以 Null 結尾。

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

規格需求

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

另請參閱

RtlUnicodeToUTF8N