RtlUTF8ToUnicodeN 函数

使用 8 位 Unicode 转换格式 (UTF-8) 代码页将指定的源字符串转换为 Unicode 字符串。

语法

NTSTATUS WINAPI RtlUTF8ToUnicodeN(
  _Out_     PWSTR  UnicodeStringDestination,
  _In_      ULONG  UnicodeStringMaxByteCount,
  _Out_opt_ PULONG UnicodeStringActualByteCount,
  _In_      PCCH   UTF8StringSource,
  _In_      ULONG  UTF8StringByteCount
);

参数

UnicodeStringDestination [out]

指向调用方分配的缓冲区的指针，该缓冲区接收转换后的字符串。

UnicodeStringMaxByteCount [in]

在 UnicodeStringDestination 处要写入的最大字节数。 如果此值导致转换的字符串被截断， RtlUTF8ToUnicodeN 将返回错误状态。

UnicodeStringActualByteCount [out， optional]

指向调用方分配的变量的指针，该变量接收已转换字符串的长度（以字节为单位）。 此参数是可选的，可以为 NULL。 如果字符串被截断，则返回的数字将计算实际截断的字符串计数。

UTF8StringSource [in]

指向要翻译的字符串的指针。

UTF8StringByteCount [in]

UTF8StringSource 中字符串的大小（以字节为单位）。

返回值

RtlUTF8ToUnicodeN 返回以下 NTSTATUS 值之一：

返回代码	说明
STATUS_SUCCESS	字符串已转换为 Unicode。
STATUS_SOME_NOT_MAPPED	遇到并替换了无效的输入字符。 此状态被视为成功状态。
STATUS_INVALID_PARAMETER	指向 UnicodeStringDestination 和 UnicodeStringActualByteCount 的指针均为 NULL。
STATUS_INVALID_PARAMETER_4	UTF8StringSource 为 NULL。
STATUS_BUFFER_TOO_SMALL	UnicodeStringDestination 已被截断。

 

备注

尽管 UnicodeStringActualByteCount 是可选的，可以为 NULL，但调用方应为其提供存储，因为接收的长度可用于确定转换是否成功。

如果输出被截断，并且遇到无效的输入字符，则该函数将返回STATUS_BUFFER_TOO_SMALL错误。

如果 UnicodeStringDestination 设置为 NULL ，则函数将返回所需的字节数，用于托管已翻译的字符串，而不会在 UnicodeStringActualByteCount 中进行任何截断。

除非 UnicodeStringDestination 和 UTF8StringSource 指针等效，否则 RtlUTF8ToUnicodeN 不会修改源字符串。 返回的 Unicode 字符串不是以 null 结尾的。

RtlUTF8ToUnicodeN 的调用方必须在 IRQL < DISPATCH_LEVEL运行。

要求

要求	值
最低受支持的客户端	Windows 7 [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 R2 [仅限桌面应用]
标头	Wdm.h
DLL	Ntdll.dll

另请参阅

RtlUnicodeToUTF8N