Export (0) Print
Expand All

RtlUnicodeToUTF8N function

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

Syntax


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

Parameters

UTF8StringDestination [out]

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

UTF8StringMaxByteCount [in]

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

UTF8StringActualByteCount [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.

UnicodeStringSource [in]

A pointer to the Unicode source string to be translated.

UnicodeStringWCharCount [in]

Size, in WChar, of the string at UnicodeStringSource.

Return value

RtlUnicodeToUTF8N returns one of the following NTSTATUS values:

Return codeDescription
STATUS_SUCCESS

The Unicode string was converted to UTF-8.

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 UTF8StringDestination and UTF8StringActualByteCount were NULL.

STATUS_INVALID_PARAMETER_4

The UnicodeStringSource was NULL.

STATUS_BUFFER_TOO_SMALL

UTF8StringDestination was truncated.

 

Remarks

Although UTF8StringActualByteCount 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. This routine does not modify the source string. It returns a null-terminated UTF-8 string if the given UnicodeStringSource included a NULL terminator and if the given UTF8StringMaxByteCount did not cause truncation.

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

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

Callers of RtlUnicodeToUTF8N 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

RtlUTF8ToUnicodeN

 

 

Community Additions

ADD
Show:
© 2014 Microsoft