共用方式為

RtlUTF8ToUnicodeN 函式 （ntifs.h）

  • 發行項

RtlUTF8ToUnicodeN 例程會將 UTF-8 字串轉換成 Unicode 字串。

語法

NTSYSAPI NTSTATUS RtlUTF8ToUnicodeN(
  [out, optional] PWSTR  UnicodeStringDestination,
  [in]            ULONG  UnicodeStringMaxByteCount,
  [out]           PULONG UnicodeStringActualByteCount,
  [in]            PCCH   UTF8StringSource,
  [in]            ULONG  UTF8StringByteCount
);

參數

[out, optional] UnicodeStringDestination

呼叫端配置的目的地緩衝區指標，例程會將 Unicode 輸出字串寫入其中。 如果此參數 NULL，例程會將輸出緩衝區的必要大小寫入 *UnicodeStringActualByteCount。

[in] UnicodeStringMaxByteCount

指定例程可以寫入至 UnicodeStringDestination 指向之緩衝區的最大位元元組數目。 如果 UnicodeStringDestination = NULL，請設定 UnicodeStringMaxByteCount = 0。

[out] UnicodeStringActualByteCount

例程將例程寫入至 UnicodeStringDestination 所指向之緩衝區的實際位元組數目的位置指標。 如果 UnicodeStringDestination 為非NULL，則此計數永遠不會超過 UnicodeStringMaxByteCount的值。 如果 UnicodeStringDestinationNULL，則此計數是包含整個輸出字串所需的位元組數目。

[in] UTF8StringSource

UTF-8 來源字串的指標。

[in] UTF8StringByteCount

指定 UTF-8 來源字串中 UTF8StringSource 參數指向的位元組數目。

傳回值

RtlUTF8ToUnicodeN 如果呼叫成功，而且輸入字串中的所有 UTF-8 字元碼都會轉換成輸出字串中對應的 Unicode 字元碼，則會傳回STATUS_SUCCESS。 如果呼叫成功，但一或多個輸入字元無效，且已轉換成 Unicode 取代字元 U+FFFD，則會傳回STATUS_SOME_NOT_MAPPED。 可能的錯誤傳回值包括下列錯誤碼：

傳回碼 描述
STATUS_BUFFER_TOO_SMALL
 UnicodeStringMaxByteCount 參數會指定緩衝區大小太小而無法包含整個輸出字串。
STATUS_INVALID_PARAMETER
 UnicodeStringDestination 和 UnicodeStringActualByteCount 參數都是 NULL。
STATUS_INVALID_PARAMETER_4
 UTF8StringSource 參數 NULL。

言論

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

如果 UnicodeStringMaxByteCount 參數指定緩衝區大小太小而無法包含整個輸出字串，則例程會傳回STATUS_BUFFER_TOO_SMALL。 在此情況下，例程會寫入與緩衝區中容納的 Unicode 字元數目一樣多，而 *UnicodeStringActualByteCount 值會指定例程已寫入緩衝區的有效位元組數目。 輸出緩衝區中包含的部分字串可能不會包含終止的 Null 字元。

您可以對 RtlUTF8ToUnicodeN 進行初始呼叫，以取得所需的輸出緩衝區大小，然後再次呼叫 RtlUTF8ToUnicodeN，以取得 Unicode 輸出字符串。 在初始呼叫中，設定 UnicodeStringDestination = NULL，UnicodeStringMaxByteCount = 0，例程會將所需的緩衝區大小寫入 *UnicodeStringActualByteCount。 接下來，配置所需大小的緩衝區，並呼叫 RtlUTF8ToUnicodeN 第二次取得 Unicode 輸出字串。

RtlUTF8ToUnicodeN 支援 Unicode Surrogate 字組。 不過，不後面接著尾端字值的 Surrogate 前置字值，或前面未加上前置字值的尾端字值，無法辨識為有效的字元，且由 Unicode 取代字元 U+FFFD 取代。

RtlUTF8ToUnicodeN 會繼續將輸入字串轉換成輸出字串，直到到達來源緩衝區的結尾或目的地緩衝區的結尾為止，從第一個開始。 例程會將輸入字串中的任何 Null 字元轉換成輸出字串中的 Null 字元。 如果輸入字串包含終止的 Null 字元，但 null 字元不在來源緩衝區的結尾，則例程會繼續超過終止的 Null 字元，直到到達可用緩衝區空間的結尾為止。

RtlUnicodeToUTF8N 例程會將 Unicode 字串轉換成 UTF-8 字串串。

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

要求

要求 價值
最低支援的用戶端 Windows 7
目標平臺 普遍
標頭 ntifs.h （include Ntifs.h， Wdm.h， Ntifs.h）
連結庫 NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

另請參閱

RtlUnicodeToUTF8N