RtlAnsiStringToUnicodeString function

Converts the specified ANSI source string into a Unicode string.

Syntax

NTSTATUS RtlAnsiStringToUnicodeString(
  PUNICODE_STRING DestinationString,
  PCANSI_STRING   SourceString,
  BOOLEAN         AllocateDestinationString
);

Parameters

DestinationString

A pointer to a UNICODE_STRING structure to hold the converted Unicode 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.

SourceString

A pointer to the ANSI_STRING structure that contains the ANSI string to be converted to Unicode.

AllocateDestinationString

Controls allocation of buffer space for the destination string.

TRUE

Buffer space is allocated for DestinationString. If set to TRUE, the buffer must be deallocated using RtlFreeUnicodeString.

FALSE

Buffer space is not allocated for DestinationString.

Return Value

The various NTSTATUS values are defined in NTSTATUS.H, which is distributed with the Windows DDK.

Return code Description
STATUS_SUCCESS
The ANSI string was converted to Unicode. On failure, the routine does not allocate any memory.

Remarks

The translation is done with respect to the current system locale information.

If caller sets AllocateDestinationString to TRUE, the routine replaces the Buffer member of DestinationString with a pointer to the buffer it allocates. The old value can be overwritten even when the routine returns an error status code.

Because there is no import library for this function, you must use GetProcAddress.

Requirements

   
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header winternl.h
DLL Ntdll.dll