Функция RtlUnicodeStringToUTF8String (ntifs.h)
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. |
Комментарии
Выходная строка UTF-8 завершается null, только если входная строка Юникода заканчивается null.
RtlUnicodeStringToUTF8String поддерживает суррогатные пары Юникода. Однако суррогатное начальное значение слова, за которым не следует значение конечного слова, или значение в конце слова, которому не предшествует значение начального слова, не распознается как допустимый код символа и заменяется символом замены Юникода U+FFFD.
RtlUnicodeStringToUTF8String продолжает преобразовывать входную строку в выходную строку, пока она не достигнет конца исходного буфера или конечного буфера в зависимости от того, что произойдет раньше. Подпрограмма преобразует все символы NULL во входной строке в символы NULL в выходной строке. Если входная строка содержит завершающий символ NULL, но пустой символ не находится в конце исходного буфера, подпрограмма продолжается до конца завершающего пустого символа, пока не достигнет конца доступного буферного пространства.
Подпрограмма RtlUTF8StringToUnicodeString преобразует строку UTF-8 в строку Юникода.
Вы можете использовать подпрограммы RtlUnicodeStringToUTF8String и RtlUTF8StringToUnicodeString для выполнения преобразования допустимых текстовых строк между форматами Юникод и UTF-8 без потерь. Однако строки с произвольными значениями данных, скорее всего, нарушают правила Юникода для кодирования суррогатных пар, а все сведения, содержащиеся в недопустимых значениях во входной строке, будут потеряны и не могут быть восстановлены из результирующей выходной строки.
Требования
Требование | Значение |
---|---|
Минимальная версия клиента | Windows 10 версии 2004 |
Верхняя часть | ntifs.h |