RtlAnsiCharToUnicodeChar routine

The RtlAnsiCharToUnicodeChar routine uses the system ANSI code page to convert a single-byte or double-byte source character to a Unicode character.

Syntax

WCHAR RtlAnsiCharToUnicodeChar(
  _Inout_ PUCHAR *SourceCharacter
);

Parameters

• SourceCharacter [in, out]
  A pointer to a character pointer. This pointer value has two levels of indirection to enable the routine to increment the pointer to the source character. If, on entry, *SourceCharacter points to a double-byte character, the routine increments *SourceCharacter by two bytes before it returns. If *SourceCharacter points to an ANSI, single-byte character, the routine increments *SourceCharacter by one byte. In this way, the routine can accommodate a double-byte character set (DBCS) that consists of a combination of single-byte and double-byte characters. For more information, see the following Remarks section.

Return value

RtlAnsiCharToUnicodeChar returns the Unicode character that corresponds to the single-byte or double-byte character that *SourceCharacter points to. If, on entry, *SourceCharacter points to an invalid character code, the function returns the Unicode space character code, 0x0020. For more information, see the following Remarks section.

Remarks

This routine has security deficiencies. Consider using the RtlAnsiStringToUnicodeString routine instead.

If, on entry, *SourceCharacter points to a one-byte buffer that contains the first byte of a two-byte character code, RtlAnsiCharToUnicodeChar overruns the buffer when it tries to read the second byte.

At system startup, the operating system determines the user language from the locale settings and installs the appropriate system ANSI code page. RtlAnsiCharToUnicodeChar uses this code page to convert a single-byte or double-byte character to the corresponding Unicode character.

If the system ANSI code page defines a single-byte character set (that is, the ANSI character set), RtlAnsiCharToUnicodeChar speeds up the conversion operation by simply zero-extending an ANSI character in the range 0x00 to 0x7f to produce the corresponding Unicode character. The routine converts the ANSI value 0x5c to the backslash character ("\"), even if the single-byte code page defines this character as the yen sign.

If, on entry, *SourceCharacter points to an invalid character code, RtlAnsiCharToUnicodeChar returns the Unicode space character code, 0x0020. The following list shows examples of invalid character codes:

• The first byte of the character code is a value that is valid only as the second byte of a two-byte character code.

• The second byte of a two-byte character code is a value that is valid only as the first byte.

This routine is not declared in a header file. However, you can copy the following declaration to your source code:

NTSYSAPI
WCHAR
NTAPI
RtlAnsiCharToUnicodeChar(
    __inout PUCHAR *SourceCharacter
    );

You can use the following routines to convert single-byte and double-byte characters to Unicode characters:

RtlAnsiStringToUnicodeSize

RtlAnsiStringToUnicodeString

RtlMultiByteToUnicodeSize

RtlMultiByteToUnicodeN

For more information about these and other string-handling routines, see Strings.

Requirements

See also

RtlAnsiStringToUnicodeSize

RtlAnsiStringToUnicodeString

RtlMultiByteToUnicodeSize

RtlMultiByteToUnicodeN

Send comments about this topic to Microsoft