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 将分配目标字符串的缓冲区空间。 此 API 仅分配 DestinationString-Buffer> 的存储。 如果 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 代理项对。 但是，不后跟尾随字值的代理前导词值或前面没有前导字值的尾随字值，不会被识别为有效字符，并由 Unicode 替换字符 U+FFFD 替换。

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

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

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

要求

要求 值
最低受支持的客户端 Windows 10 版本 2004
目标平台 通用
标头 ntifs.h (包括 Ntifs.h、Wdm.h、Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

另请参阅

RtlFreeUnicodeString

RtlUnicodeStringToUTF8String