Функция RtlUTF8ToUnicodeN (wdm.h)

Статья
06/01/2023

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

Синтаксис

NTSYSAPI NTSTATUS RtlUTF8ToUnicodeN(
  [out, optional] PWSTR  UnicodeStringDestination,
  [in]            ULONG  UnicodeStringMaxByteCount,
  [out]           PULONG UnicodeStringActualByteCount,
  [in]            PCCH   UTF8StringSource,
  [in]            ULONG  UTF8StringByteCount
);

Параметры

[out, optional] UnicodeStringDestination

Указатель на буфер назначения, выделенный вызывающим объектом, в который подпрограмма записывает выходную строку Юникода. Если этот параметр имеет значение NULL, подпрограмма записывает требуемый размер выходного буфера в файл *UnicodeStringActualByteCount.

[in] UnicodeStringMaxByteCount

Задает максимальное число байтов, которое подпрограмма может записывать в буфер, на который указывает ЮникодStringDestination . Если UnicodeStringDestination = NULL, задайте unicodeStringMaxByteCount = 0.

[out] UnicodeStringActualByteCount

Указатель на расположение, в которое подпрограмма записывает фактическое количество байтов, записанных подпрограммой в буфер, на который указывает UnicodeStringDestination . Если значение UnicodeStringDestination не равно NULL, это число никогда не превышает значение UnicodeStringMaxByteCount. Если UnicodeStringDestination имеет значение NULL, это количество байтов, необходимых для хранения всей выходной строки.

[in] UTF8StringSource

Указатель на исходную строку UTF-8.

[in] UTF8StringByteCount

Указывает количество байтов в исходной строке UTF-8, на которую указывает параметр UTF8StringSource .

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

RtlUTF8ToUnicodeN возвращает STATUS_SUCCESS, если вызов выполнен успешно и все коды символов UTF-8 во входной строке были преобразованы в соответствующие коды символов Юникода в выходной строке. Он возвращает STATUS_SOME_NOT_MAPPED, если вызов выполнен успешно, но один или несколько входных символов были недопустимыми и были преобразованы в символ замены Юникода U+FFFD. Возможные возвращаемые значения ошибок включают следующие коды ошибок:

Код возврата	Описание
STATUS_BUFFER_TOO_SMALL	Параметр UnicodeStringMaxByteCount указывает размер буфера, который слишком мал, чтобы содержать всю выходную строку.
STATUS_INVALID_PARAMETER	Параметры UnicodeStringDestination и UnicodeStringActualByteCount имеют значение NULL.
STATUS_INVALID_PARAMETER_4	Параметр UTF8StringSource имеет значение NULL.

Подпрограмма возвращает STATUS_BUFFER_TOO_SMALL, если параметр UnicodeStringMaxByteCount указывает размер буфера, который слишком мал, чтобы содержать всю выходную строку. В этом случае подпрограмма записывает столько символов Юникода, сколько поместится в буфере, а значение *UnicodeStringActualByteCount указывает количество допустимых байтов, записанных подпрограммой в буфер. Частичная строка, содержащаяся в выходном буфере, может не содержать завершающий символ NULL.

Вы можете выполнить первоначальный вызов RtlUTF8ToUnicodeN , чтобы получить требуемый размер выходного буфера, а затем снова вызвать RtlUTF8ToUnicodeN , чтобы получить выходную строку Юникода. В начальном вызове задайте UnicodeStringDestination = NULL и UnicodeStringMaxByteCount = 0, а подпрограмма запишет требуемый размер буфера в значение *UnicodeStringActualByteCount. Затем выделите буфер требуемого размера и вызовите RtlUTF8ToUnicodeN во второй раз, чтобы получить выходную строку Юникода.

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

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

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

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

Требования

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

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

RtlUnicodeToUTF8N