大网数据广告活动
Windows 系统接口

RtlUTF8ToUnicodeN function (Wdm.h)

· 52CE 我爱测

Translates the specified source string into a Unicode string, using the 8-bit Unicode Transformation Format (UTF-8) code page.

Translates the specified source string into a Unicode string, using the 8-bit Unicode Transformation Format (UTF-8) code page.

Syntax

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

Parameters

UnicodeStringDestination [out]

A pointer to a caller-allocated buffer that receives the translated string.

UnicodeStringMaxByteCount [in]

Maximum number of bytes to be written at UnicodeStringDestination. If this value causes the translated string to be truncated, RtlUTF8ToUnicodeN returns an error status.

UnicodeStringActualByteCount [out, optional]

A pointer to a caller-allocated variable that receives the length, in bytes, of the translated string. This parameter is optional and can be NULL. If the string is truncated then the returned number counts the actual truncated string count.

UTF8StringSource [in]

A pointer to the string to be translated.

UTF8StringByteCount [in]

Size, in bytes, of the string at UTF8StringSource.

Return value

RtlUTF8ToUnicodeN returns one of the following NTSTATUS values:

Return code Description
STATUS_SUCCESS The string was converted to Unicode.
STATUS_SOME_NOT_MAPPED An invalid input character was encountered and replaced. This status is considered a success status.
STATUS_INVALID_PARAMETER Both pointers to UnicodeStringDestination and UnicodeStringActualByteCount were NULL.
STATUS_INVALID_PARAMETER_4 The UTF8StringSource was NULL.
STATUS_BUFFER_TOO_SMALL UnicodeStringDestination was truncated.

Remarks

Although UnicodeStringActualByteCount is optional and can be NULL, callers should provide storage for it, because the received length can be used to determine whether the conversion was successful.

If the output is truncated and an invalid input character is encountered then the function returns STATUS_BUFFER_TOO_SMALL error.

If the UnicodeStringDestination is set to NULL the function will return the required number of bytes to host the translated string without any truncation in UnicodeStringActualByteCount.

RtlUTF8ToUnicodeN does not modify the source string unless the UnicodeStringDestination and UTF8StringSource pointers are equivalent. The returned Unicode string is not null-terminated.

Callers of RtlUTF8ToUnicodeN must be running at IRQL < DISPATCH_LEVEL.

Requirements

Requirement Value
Minimum supported client Windows 7 [desktop apps only]
Minimum supported server Windows Server 2008 R2 [desktop apps only]
Header Wdm.h
DLL Ntdll.dll

See also

RtlUnicodeToUTF8N

Source: Microsoft Learn / Windows Win32 documentation by Microsoft and contributors. Documentation licensed CC BY 4.0. Code samples are covered by the MIT License. Converted from Markdown, with links normalized and embedded media omitted.

资料来源与适用范围

资料来源
Microsoft Learn / Windows Win32 documentation
适用范围
Windows Win32 API · Source date 02/21/2019
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY 4.0 (documentation), MIT (code samples)

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。