RtlMultiByteToUnicodeN function (ntifs.h)
The RtlMultiByteToUnicodeN routine translates the specified source string into a Unicode string, using the current system ANSI code page (ACP). The source string is not necessarily from a multibyte character set.
Syntax
NTSYSAPI NTSTATUS RtlMultiByteToUnicodeN(
[out] PWCH UnicodeString,
[in] ULONG MaxBytesInUnicodeString,
[out, optional] PULONG BytesInUnicodeString,
[in] const CHAR *MultiByteString,
[in] ULONG BytesInMultiByteString
);
Parameters
[out] UnicodeString
Pointer to a caller-allocated buffer that receives the translated string. UnicodeString buffer must not overlap with MultiByteString buffer.
[in] MaxBytesInUnicodeString
Maximum number of bytes to be written at UnicodeString. If this value causes the translated string to be truncated, RtlMultiByteToUnicodeN does not return an error status.
[out, optional] BytesInUnicodeString
Pointer to a caller-allocated variable that receives the length, in bytes, of the translated string. This parameter can be NULL.
[in] MultiByteString
Pointer to the string to be translated.
[in] BytesInMultiByteString
Size, in bytes, of the string at MultiByteString.
Return value
RtlMultiByteToUnicodeN returns STATUS_SUCCESS.
Remarks
RtlMultiByteToUnicodeN supports only precomposed Unicode characters that are mapped to the current system ANSI code page installed at system boot.
Although BytesInUnicodeString 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 current system code page defines a single-byte character set, all ANSI characters in the range 0x00 to 0x7f are simply zero-extended in the corresponding Unicode string to speed the conversion operation. The ANSI value 0x5c in such a code page is translated into the backslash character, even if the current single-byte code page defines this character as the Yen sign.
RtlMultiByteToUnicodeN does not modify the source string unless the UnicodeString and MultiByteString pointers are equivalent. The returned Unicode string is not null-terminated.
Like RtlMultiByteToUnicodeSize, RtlMultiByteToUnicodeN supports only precomposed Unicode characters that are mapped to the current system ANSI code page installed at system boot.
For information about other string-handling routines, see Run-Time Library (RTL) Routines.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Header | ntifs.h (include Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe (kernel mode); Ntdll.dll (user mode) |
| IRQL | < DISPATCH_LEVEL |