RtlAnsiStringToUnicodeString

RtlAnsiStringToUnicodeString converts the given ANSI source string into a Unicode string.

NTSTATUS 
  RtlAnsiStringToUnicodeString(
    IN OUT PUNICODE_STRING  DestinationString,
    IN PANSI_STRING  SourceString,
    IN BOOLEAN  AllocateDestinationString
    );

Parameters

DestinationString

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

Pointer to the ANSI string to be converted to Unicode.

AllocateDestinationString

Specifies TRUE if this routine should allocate the buffer space for the destination string. If it does, the caller must deallocate the buffer by calling RtlFreeUnicodeString.

Return Value

If the conversion succeeds, RtlAnsiStringToUnicodeString returns STATUS_SUCCESS. On failure, the routine does not allocate any memory.

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

The translation conforms 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.

Callers of RtlAnsiStringToUnicodeString must be running at IRQL = PASSIVE_LEVEL.

See Also

ANSI_STRING, UNICODE_STRING, RtlAnsiStringToUnicodeSize, RtlFreeUnicodeString, RtlInitAnsiString, RtlUnicodeStringToAnsiString