通过

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 返回STATUS_SUCCESS如果调用成功，并且输入字符串中的所有 UTF-8 字符代码都转换为输出字符串中的相应 Unicode 字符代码。 如果调用成功，但一个或多个输入字符无效，并且已转换为 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 代理项对。 但是，不后跟尾随字值的代理项前导词值或前导词值前面的尾随词值不能识别为有效字符，并且被 Unicode 替换字符 U+FFFD 替换。

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

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

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

要求

要求 价值
最低支持的客户端 Windows 7
目标平台 普遍
标头 ntifs.h （包括 Ntifs.h、Wdm.h、Ntifs.h）
库 NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

另请参阅

RtlUnicodeToUTF8N