RtlUnicodeStringToUTF8String - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTRTL_H
#if (PHNT_VERSION >= PHNT_WINDOWS_10_20H1)
NTSYSAPI
NTSTATUS
NTAPI
RtlUnicodeStringToUTF8String(
_Inout_ PUTF8_STRING DestinationString,
_In_ PCUNICODE_STRING SourceString,
_In_ BOOLEAN AllocateDestinationString
);
View code on GitHub// ntifs.h
NTSYSAPI NTSTATUS RtlUnicodeStringToUTF8String(
PUTF8_STRING DestinationString,
PCUNICODE_STRING SourceString,
BOOLEAN AllocateDestinationString
);
View the official Windows Driver Kit DDI reference// wdm.h
NTSYSAPI NTSTATUS RtlUnicodeStringToUTF8String(
PUTF8_STRING DestinationString,
PCUNICODE_STRING SourceString,
BOOLEAN AllocateDestinationString
);
View the official Windows Driver Kit DDI referenceRtlUnicodeStringToUTF8String converts the specified Unicode string into a UTF-8 string.
DestinationStringPointer to the buffer in which the converted output UTF-8 string is placed. The DestinationString->MaximumLength field is set only if AllocateDestinationString is TRUE.
SourceStringPointer to the Unicode string to be converted to UTF-8.
AllocateDestinationStringBoolean value. When set TRUE, RtlUnicodeStringToUTF8String allocates the buffer space for the destination string. Only storage for DestinationString->Buffer is allocated by this API. If RtlUnicodeStringToUTF8String does the buffer allocation, then the caller must deallocate the buffer using RtlFreeUTF8String.
This function returns STATUS_SUCCESS when the conversion is successful. Possible error or warning codes include:
| Code | Description |
|---|---|
| STATUS_INVALID_PARAMETERX | Error: One of the parameter values is invalid. |
| STATUS_NO_MEMORY | Error: RtlUnicodeStringToUTF8String was unable to allocate buffer space. |
| STATUS_BUFFER_OVERFLOW | Warning: The converted string in DestinationString->Buffer is truncated due to insufficient space in the destination buffer. |
| STATUS_SOME_NOT_MAPPED | Warning: The call was successful, but one or more of the input characters were invalid and were replaced by the Unicode replacement character, U+FFFD, before being converted to UTF-8. |
The UTF-8 output string is null-terminated only if the Unicode input string is null-terminated.
RtlUnicodeStringToUTF8String supports Unicode surrogate pairs. However, a surrogate leading word value that is not followed by a trailing word value, or a trailing word value that is not preceded by a leading word value, is not recognized as a valid character code and is replaced by the Unicode replacement character, U+FFFD.
RtlUnicodeStringToUTF8String continues to convert the input string to an output string until it reaches the end of the source buffer or the end of the destination buffer, whichever occurs first. The routine converts any null characters in the input string to null characters in the output string. If the input string contains a terminating null character, but the null character is not located at the end of the source buffer, the routine continues past the terminating null character until it reaches the end of the available buffer space.
The RtlUTF8StringToUnicodeString routine converts a UTF-8 string to a Unicode string.
You can use the RtlUnicodeStringToUTF8String and RtlUTF8StringToUnicodeString routines to perform a lossless conversion of valid text strings between the Unicode and UTF-8 formats. However, strings that have arbitrary data values are likely to violate the Unicode rules for encoding surrogate pairs, and any information that is contained in the invalid values in an input string is lost and cannot be recovered from the resulting output string.
The RtlUnicodeStringToUTF8String function converts the specified Unicode source string into an UTF8 string.
DestinationStringPointer to a UTF8_STRING structure to hold the converted UTF8 string. If AllocateDestinationString is TRUE, the routine allocates a new buffer to hold the string data, and updates the Buffer member of DestinationString to point to the new buffer. Otherwise, the routine uses the currently specified buffer to hold the string. The maximum length field is only set if AllocateDestinationString is TRUE.
SourceStringPointer to the Unicode source string to be converted to UTF8.
AllocateDestinationStringTRUE if this routine is to allocate the buffer space for the DestinationString. If it does, the buffer must be deallocated by calling RtlFreeUTF8String.
If the conversion succeeds, RtlUnicodeStringToUTF8String returns STATUS_SUCCESS. On failure, the routine does not allocate memory or perform a conversion.