Функция 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->буфера. Если RtlUTF8StringToUnicodeString выделяет буфер, вызывающий объект должен освободить буфер с помощью RtlFreeUnicodeString.
Возвращаемое значение
Эта функция возвращает STATUS_SUCCESS при успешном преобразовании. Возможные коды ошибок или предупреждений:
| Код | Описание |
|---|---|
| STATUS_INVALID_PARAMETERX | Ошибка: одно из значений параметров недопустимо. |
| STATUS_NO_MEMORY | Ошибка: RtlUTF8StringToUnicodeString не удалось выделить буферное пространство. |
| STATUS_BUFFER_OVERFLOW | Предупреждение. Преобразованная строка в DestinationString->буфера усечена из-за нехватки места в буфере назначения. |
| STATUS_SOME_NOT_MAPPED | Предупреждение. Вызов выполнен успешно, но один или несколько входных символов были недопустимыми и были преобразованы символом замены Юникода U+FFFD, прежде чем преобразовывать его в UTF-8. |
Замечания
Выходная строка Юникода завершается null, только если входная строка UTF-8 завершается null.
RtlUTF8StringToUnicodeString поддерживает суррогатные пары Юникода. Тем не менее, суррогатное значение слова, за которым не следует значение конечного слова, или конечное значение слова, которое не предшествует начальному значению слова, не распознается как допустимый символ и заменяется символом замены Юникода U+FFFD.
RtlUTF8StringToUnicodeString продолжает преобразовывать входную строку в выходную строку, пока она не достигнет конца исходного буфера или конца целевого буфера. Подпрограмма преобразует все пустые символы в входной строке в символы NULL в выходной строке. Если входная строка содержит завершающий символ NULL, но пустой символ не находится в конце исходного буфера, подпрограмма продолжается до конца конца пустого символа, пока не достигнет конца доступного буферного пространства.
Подпрограмма RtlUnicodeStringToUTF8String преобразует строку Юникода в строку UTF-8.
Вы можете использовать подпрограммы RtlUTF8StringToUnicodeString и RtlUnicodeStringToUTF8String для выполнения безвозмездного преобразования допустимых текстовых строк между форматами UTF-8 и Юникодом. Однако строки с произвольными значениями данных, скорее всего, нарушают правила Юникода для кодирования суррогатных пар, и все сведения, содержащиеся в недопустимых значениях входной строки, теряются и не могут быть восстановлены из результирующей выходной строки.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows 10 версии 2004 |
| целевая платформа | Всеобщий |
| заголовка | ntifs.h (include Ntifs.h, Wdm.h, Ntifs.h) |
| библиотеки | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |