Export (0) Print
Expand All

RtlUTF8ToUnicodeN function

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 UnicodeStringMaxWCharCount,
  _Out_opt_  PULONG UnicodeStringActualWCharCount,
  _In_       PCCH UTF8StringSource,
  _In_       ULONG UTF8StringByteCount
);

Parameters

UnicodeStringDestination [out]

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

UnicodeStringMaxWCharCount [in]

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

UnicodeStringActualWCharCount [out, optional]

A pointer to a caller-allocated variable that receives the length, in WCHAR, 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 codeDescription
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 UnicodeStringActualWCharCount were NULL.

STATUS_INVALID_PARAMETER_4

The UTF8StringSource was NULL.

STATUS_BUFFER_TOO_SMALL

UnicodeStringDestination was truncated.

 

Remarks

Although UnicodeStringActualWCharCount 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 WCHAR to host the translated string without any truncation in UnicodeStringActualWCharCount.

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

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

 

 

Community Additions

ADD
Show:
© 2014 Microsoft