共用方式為

RtlUnicodeToUTF8N 函式 (wdm.h)

  • 發行項

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

語法

NTSYSAPI NTSTATUS RtlUnicodeToUTF8N(
  [out] PCHAR  UTF8StringDestination,
  [in]  ULONG  UTF8StringMaxByteCount,
  [out] PULONG UTF8StringActualByteCount,
  [in]  PCWCH  UnicodeStringSource,
  [in]  ULONG  UnicodeStringByteCount
);

參數

[out] UTF8StringDestination

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

[in] UTF8StringMaxByteCount

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

[out] UTF8StringActualByteCount

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

[in] UnicodeStringSource

Unicode 來源字串的指標。

[in] UnicodeStringByteCount

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

傳回值

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

傳回碼 Description
STATUS_BUFFER_TOO_SMALL
 UTF8StringMaxByteCount 參數會指定緩衝區大小太小而無法包含整個輸出字串。
STATUS_INVALID_PARAMETER
 UTF8StringDestination 和 UTF8StringActualByteCount 参數都是 NULL。
STATUS_INVALID_PARAMETER_4
 UnicodeStringSource 參數為 NULL。
STATUS_INVALID_PARAMETER_5
 UnicodeStringByteCount 不是 (WCHAR) 的 整數倍數。

備註

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

如果 UTF8StringMaxByteCount 參數指定緩衝區大小太小而無法包含整個輸出字串，則例程會傳回STATUS_BUFFER_TOO_SMALL。 在此情況下，例程會寫入符合緩衝區的 UTF-8 字元數目，而 *UTF8StringActualByteCount 值會指定例程寫入緩衝區的有效位元組數目。 輸出緩衝區中包含的部分字串可能不會包含終止的 Null 字元。

您可以對 RtlUnicodeToUTF8N 進行初始呼叫，以取得所需的輸出緩衝區大小，然後再次呼叫 RtlUnicodeToUTF8N 以取得 Unicode 輸出字串。 在初始呼叫中，設定 UTF8StringDestination = NULL 和 UTF8StringMaxByteCount = 0，而例程會將所需的緩衝區大小寫入 *UTF8StringActualByteCount。 接下來，配置必要大小的緩衝區，並再次呼叫 RtlUnicodeToUTF8N 以取得 UTF-8 輸出字串。

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

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

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

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

規格需求

需求 值
最低支援的用戶端 可在 Windows 7 和更新版本的 Windows 中使用。
目標平台 Universal
標頭 wdm.h (包括 Ntifs.h、Wdm.h、Ntifs.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL PASSIVE_LEVEL

另請參閱

RtlUTF8ToUnicodeN