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

  • Статья

Подпрограмма 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.

Комментарии

Выходная строка Юникода заканчивается null, только если входная строка UTF-8 заканчивается null.

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