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 的值。 如果 UTF8StringDestinationNULL,则此计数是包含整个输出字符串所需的字节数。

[in] UnicodeStringSource

指向 Unicode 源字符串的指针。

[in] UnicodeStringByteCount

指定 UnicodeStringSource 参数指向的 Unicode 源 字符串中的字节数。

返回值

如果调用成功,并且输入字符串中的所有 Unicode 字符代码都转换为输出字符串中的相应 UTF-8 字符代码,RtlUnicodeToUTF8N 将返回STATUS_SUCCESS。 如果调用成功,但一个或多个输入字符无效,并在转换为 UTF-8 之前被 Unicode 替换字符 U+FFFD 替换,则返回STATUS_SOME_NOT_MAPPED。 可能的错误返回值包括以下错误代码:

返回代码 说明
STATUS_BUFFER_TOO_SMALL
UTF8StringMaxByteCount 参数指定缓冲区大小太小,无法包含整个输出字符串。
STATUS_INVALID_PARAMETER
UTF8StringDestinationUTF8StringActualByteCount 参数均为 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 = NULLUTF8StringMaxByteCount = 0,例程会将所需的缓冲区大小写入 *UTF8StringActualByteCount。 接下来,分配所需大小的缓冲区,并再次调用 RtlUnicodeToUTF8N 以获取 UTF-8 输出字符串。

RtlUnicodeToUTF8N 支持 Unicode 代理项对。 但是,不后跟尾随字值的代理前导词值或前面没有前导词值的尾随字值,不会被识别为有效的字符代码,并由 Unicode 替换字符 U+FFFD 替换。

RtlUnicodeToUTF8N 继续将输入字符串转换为输出字符串,直到到达源缓冲区的末尾或目标缓冲区的末尾(以先出现者为准)。 例程将输入字符串中的任何 null 字符转换为输出字符串中的 null 字符。 如果输入字符串包含终止 null 字符,但 null 字符不位于源缓冲区的末尾,则例程将继续超过终止 null 字符,直到到达可用缓冲区空间的末尾。

RtlUTF8ToUnicodeN 例程将 UTF-8 字符串转换为 Unicode 字符串。

可以使用 RtlUnicodeToUTF8NRtlUTF8ToUnicode 例程在 Unicode 和 UTF-8 格式之间执行有效文本字符串的无损转换。 但是,具有任意数据值的字符串可能会违反编码代理项对的 Unicode 规则,并且输入字符串中无效值中包含的任何信息都将丢失,并且无法从生成的输出字符串中恢复。

要求

要求
最低受支持的客户端 在 Windows 7 和更高版本的 Windows 中可用。
目标平台 通用
标头 wdm.h (包括 Ntifs.h、Wdm.h、Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

另请参阅

RtlUTF8ToUnicodeN