RtlUnicodeToUTF8N 函数

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

语法

NTSTATUS WINAPI RtlUnicodeToUTF8N(
  _Out_     PCHAR  UTF8StringDestination,
  _In_      ULONG  UTF8StringMaxByteCount,
  _Out_opt_ PULONG UTF8StringActualByteCount,
  _In_      PCWSTR UnicodeStringSource,
  _In_      ULONG  UnicodeStringByteCount
);

参数

UTF8StringDestination [out]

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

UTF8StringMaxByteCount [in]

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

UTF8StringActualByteCount [out， optional]

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

UnicodeStringSource [in]

指向要转换的 Unicode 源字符串的指针。

*UnicodeStringByteCount * [in]

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

返回值

RtlUnicodeToUTF8N 返回以下 NTSTATUS 值之一：

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

 

备注

尽管 UTF8StringActualByteCount 是可选的，可以为 NULL，但调用方应为其提供存储，因为接收的长度可用于确定转换是否成功。 此例程不会修改源字符串。 如果给定的 UnicodeStringSource 包含 NULL 终止符，并且给定的 UTF8StringMaxByteCount 不会导致截断，则返回以 null 结尾的 UTF-8 字符串。

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

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

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

要求

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

另请参阅

RtlUTF8ToUnicodeN