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

Статья
08/07/2023

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

Синтаксис

NTSYSAPI NTSTATUS RtlUnicodeStringToUTF8String(
  PUTF8_STRING     DestinationString,
  PCUNICODE_STRING SourceString,
  BOOLEAN          AllocateDestinationString
);

Параметры

DestinationString

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

SourceString

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

AllocateDestinationString

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

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

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

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

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

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

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

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 10 версии 2004
Верхняя часть	ntifs.h

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

RtlFreeUTF8String

RtlUTF8StringToUnicodeString

Share via