Функция RtlUTF8StringToUnicodeString (ntifs.h)

Статья
08/07/2023

Подпрограмма RtlUTF8StringToUnicodeString преобразует указанную строку UTF-8 в строку Юникода.

Синтаксис

NTSYSAPI NTSTATUS RtlUTF8StringToUnicodeString(
  PUNICODE_STRING DestinationString,
  PUTF8_STRING    SourceString,
  BOOLEAN         AllocateDestinationString
);

Параметры

DestinationString

Указатель на буфер, в котором хранится преобразованная строка Юникода. Поле DestinationString-MaximumLength> задается, только если свойство AllocateDestinationString имеет значение TRUE.

SourceString

Указатель на исходную строку UTF-8, которая должна быть преобразована в Юникод.

AllocateDestinationString

. Если задано значение TRUE, RtlUTF8StringToUnicodeString выделяет буферное пространство для строки назначения. Этот API выделяет только хранилище для DestinationString-Buffer>. Если RtlUTF8StringToUnicodeString выполняет выделение буфера, вызывающий объект должен освободить буфер с помощью RtlFreeUnicodeString.

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

Эта функция возвращает STATUS_SUCCESS после успешного преобразования. Возможные коды ошибок или предупреждений:

Код	Описание
STATUS_INVALID_PARAMETERX	Ошибка: одно из значений параметра является недопустимым.
STATUS_NO_MEMORY	Ошибка : RtlUTF8StringToUnicodeString не удалось выделить буферное пространство.
STATUS_BUFFER_OVERFLOW	Предупреждение. Преобразованная строка в DestinationString-Buffer усекается из-за> нехватки места в буфере назначения.
STATUS_SOME_NOT_MAPPED	Предупреждение. Вызов был выполнен успешно, но один или несколько входных символов были недопустимы и были преобразованы символом замены Юникода U+FFFD перед преобразованием в UTF-8.

RtlUTF8StringToUnicodeString поддерживает суррогатные пары Юникода. Однако суррогатное начальное значение слова, за которым не следует значение конечного слова, или значение в конце слова, которому не предшествует значение начального слова, не распознается как допустимый символ и заменяется символом замены Юникода U+FFFD.

RtlUTF8StringToUnicodeString продолжает преобразовывать входную строку в выходную строку, пока она не достигнет конца исходного буфера или конца буфера назначения, в зависимости от того, что произойдет раньше. Подпрограмма преобразует все символы NULL во входной строке в символы NULL в выходной строке. Если входная строка содержит завершающий символ NULL, но пустой символ не находится в конце исходного буфера, подпрограмма продолжается до конца завершающего пустого символа, пока не достигнет конца доступного буферного пространства.

Подпрограмма RtlUnicodeStringToUTF8String преобразует строку Юникода в строку UTF-8.

Вы можете использовать подпрограммы RtlUTF8StringToUnicodeString и RtlUnicodeStringToUTF8String для выполнения преобразования допустимых текстовых строк без потерь между форматами UTF-8 и Юникод. Однако строки с произвольными значениями данных, скорее всего, нарушают правила Юникода для кодирования суррогатных пар, а все сведения, содержащиеся в недопустимых значениях во входной строке, будут потеряны и не могут быть восстановлены из результирующей выходной строки.

Требования

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

См. также раздел

RtlFreeUnicodeString

RtlUnicodeStringToUTF8String

Share via