Функция RtlAnsiStringToUnicodeString (wdm.h)

Статья
03/08/2023

RtlAnsiStringToUnicodeString преобразует заданную исходную строку ANSI в строку Юникода.

Синтаксис

NTSYSAPI NTSTATUS RtlAnsiStringToUnicodeString(
  [in, out] PUNICODE_STRING DestinationString,
  [in]      PCANSI_STRING   SourceString,
  [in]      BOOLEAN         AllocateDestinationString
);

Параметры

[in, out] DestinationString

Указатель на структуру UNICODE_STRING для хранения преобразованной строки Юникода. Если параметр AllocateDestinationString имеет значение TRUE, подпрограмма выделяет новый буфер для хранения строковых данных и обновляет элемент Bufferэлемента DestinationString , чтобы он указывал на новый буфер. В противном случае подпрограмма использует указанный в данный момент буфер для хранения строки.

[in] SourceString

Указатель на строку ANSI, которая будет преобразована в Юникод.

[in] AllocateDestinationString

Указывает, должна ли эта подпрограмма выделять буферное пространство для строки назначения. Если это так, вызывающий объект должен освободить буфер, вызвав RtlFreeUnicodeString.

Возвращаемое значение

Если преобразование выполнено успешно, RtlAnsiStringToUnicodeString возвращает STATUS_SUCCESS. При сбое подпрограмма не выделяет память.

Если вызывающий объект присваивает свойству AllocateDestinationString значение TRUE, подпрограмма заменяет элемент Bufferэлемента DestinationString указателем на выделенный буфер. Старое значение можно перезаписать, даже если подпрограмма возвращает код состояния ошибки.

Эта подпрограмма не объявляется в файле заголовка. Однако в исходный код можно скопировать следующее объявление:

NTSYSAPI
WCHAR
NTAPI
RtlAnsiCharToUnicodeChar(
    __inout PUCHAR *SourceCharacter
    );

Для преобразования однобайтовых и двухбайтовых символов в символы Юникода можно использовать следующие процедуры:

Дополнительные сведения об этих и других подпрограммах обработки строк см. в статье Подпрограммы библиотеки времени выполнения (RTL).

RtlAnsiCharToUnicodeChar имеет недостатки безопасности. Вместо этого рекомендуется использовать подпрограмму RtlAnsiStringToUnicodeString .

Если при вводе *SourceCharacter указывает на однобайтовый буфер, содержащий первый байт двухбайтового символьного кода, RtlAnsiCharToUnicodeChar переползает буфер при попытке прочитать второй байт.

При запуске системы операционная система определяет язык пользователя из параметров языкового стандарта и устанавливает соответствующую системную кодовую страницу ANSI. RtlAnsiCharToUnicodeChar использует эту кодовую страницу для преобразования однобайтового или двухбайтового символа в соответствующий символ Юникода.

Если системная кодовая страница ANSI определяет однобайтовый набор символов (то есть набор символов ANSI), RtlAnsiCharToUnicodeChar ускоряет операцию преобразования, просто расширяя символ ANSI в диапазоне, 0x00 для 0x7f для создания соответствующего символа Юникода. Подпрограмма преобразует значение ANSI 0x5c в символ обратной косой черты ("\"), даже если однобайтовая кодовая страница определяет этот символ как знак иены.

Если при вводе *SourceCharacter указывает на недопустимый код символов, RtlAnsiCharToUnicodeChar возвращает код пробела в Юникоде 0x0020. В следующем списке показаны примеры недопустимых кодов символов:

Первый байт кода символа — это значение, допустимое только в качестве второго байта двухбайтового кода символов.
Второй байт двухбайтового символьного кода является значением, допустимым только в качестве первого байта.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL