RtlUTF8StringToUnicodeString 函式 (ntifs.h)

  • 發行項

RtlUTF8StringToUnicodeString 例程會將指定的 UTF-8 字串轉換為 Unicode 字串串。

語法

NTSYSAPI NTSTATUS RtlUTF8StringToUnicodeString(
  PUNICODE_STRING DestinationString,
  PUTF8_STRING    SourceString,
  BOOLEAN         AllocateDestinationString
);

參數

DestinationString

儲存已轉換輸出 Unicode 字串之緩衝區的指標。 只有在 AllocateDestinationString 為 TRUE 時，才會設定 DestinationString-MaximumLength> 字段。

SourceString

要轉換成 Unicode 的 UTF-8 來源字串指標。

AllocateDestinationString

布林值。 設定 TRUE 時， RtlUTF8StringToUnicodeString 會配置目的地字串的緩衝區空間。 只有 DestinationString-Buffer> 的記憶體是由此 API 所配置。 如果 RtlUTF8StringToUnicodeString 執行緩衝區配置，則呼叫端必須使用 RtlFreeUnicodeString 解除分配緩衝區。

傳回值

當轉換成功時，此函式會傳回STATUS_SUCCESS。 可能的錯誤或警告碼包括：

程式碼 描述
STATUS_INVALID_PARAMETERX 錯誤：其中一個參數值無效。
STATUS_NO_MEMORY 錯誤： RtlUTF8StringToUnicodeString 無法配置緩衝區空間。
STATUS_BUFFER_OVERFLOW 警告：DestinationString-Buffer> 中的已轉換字串因目的地緩衝區空間不足而遭到截斷。
STATUS_SOME_NOT_MAPPED 警告：呼叫成功，但一或多個輸入字元無效，而且在轉換成 UTF-8 之前，Unicode 取代字元 U+FFFD 已轉換。

備註

只有在UTF-8輸入字串為Null終止時，Unicode 輸出字串才會以 Null 終止。

RtlUTF8StringToUnicodeString 支援 Unicode Surrogate 配對。 不過，未後面接著尾端字值的 Surrogate 前置字值，或是前面沒有前置字值的尾端字值，無法辨識為有效的字元，並且會由 Unicode 取代字元 U+FFFD 取代。

RtlUTF8StringToUnicodeString 會繼續將輸入字串轉換成輸出字串，直到到達來源緩衝區的結尾或目的地緩衝區的結尾為止，只要先發生。 例程會將輸入字串中的任何 Null 字元轉換成輸出字串中的 Null 字元。 如果輸入字串包含終止 Null 字元，但 Null 字元不在來源緩衝區的結尾，則例程會繼續超過終止 Null 字元，直到到達可用緩衝區空間的結尾為止。

RtlUnicodeStringToUTF8String 例程會將 Unicode 字串轉換為 UTF-8 字串串。

您可以使用 RtlUTF8StringToUnicodeString 和 RtlUnicodeStringToUTF8String 例程來執行 UTF-8 與 Unicode 格式之間有效文字字符串的不遺失轉換。 不過，具有任意數據值的字串可能會違反編碼代理字組的 Unicode 規則，而且輸入字串中無效值中包含的任何資訊都會遺失，而且無法從產生的輸出字元串中復原。

規格需求

需求 值
最低支援的用戶端 Windows 10 (版本 2004)
目標平台 Universal
標頭 ntifs.h (包括 Ntifs.h、Wdm.h、Ntifs.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL PASSIVE_LEVEL

另請參閱

RtlFreeUnicodeString

RtlUnicodeStringToUTF8String