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

Статья
03/14/2023

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

Синтаксис

NTSYSAPI NTSTATUS RtlUnicodeToUTF8N(
  [out] PCHAR  UTF8StringDestination,
  [in]  ULONG  UTF8StringMaxByteCount,
  [out] PULONG UTF8StringActualByteCount,
  [in]  PCWCH  UnicodeStringSource,
  [in]  ULONG  UnicodeStringByteCount
);

Параметры

[out] UTF8StringDestination

Указатель на выделенный вызывающим целевым буфером, в который подпрограмма записывает выходную строку UTF-8. Если этот параметр имеет значение NULL, подпрограмма записывает требуемый размер выходного буфера в *UTF8StringActualByteCount.

[in] UTF8StringMaxByteCount

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

[out] UTF8StringActualByteCount

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

[in] UnicodeStringSource

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

[in] UnicodeStringByteCount

Указывает количество байтов в исходной строке Юникода, на которое указывает параметр UnicodeStringSource .

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

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

Код возврата	Описание
STATUS_BUFFER_TOO_SMALL	Параметр UTF8StringMaxByteCount указывает размер буфера, который слишком мал, чтобы содержать всю выходную строку.
STATUS_INVALID_PARAMETER	Параметры UTF8StringDestination и UTF8StringActualByteCount имеют значение NULL.
STATUS_INVALID_PARAMETER_4	Параметр ЮникодStringSource имеет значение NULL.
STATUS_INVALID_PARAMETER_5	UnicodeStringByteCount не является целым числом, кратным sizeof(WCHAR).

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

Вы можете выполнить первоначальный вызов RtlUnicodeToUTF8N , чтобы получить требуемый размер буфера вывода, а затем снова вызвать RtlUnicodeToUTF8N , чтобы получить выходную строку Юникода. В начальном вызове задайте UTF8StringDestination = NULL и UTF8StringMaxByteCount = 0, и подпрограмма запишет необходимый размер буфера в значение *UTF8StringActualByteCount. Затем выделите буфер требуемого размера и вызовите RtlUnicodeToUTF8N во второй раз, чтобы получить выходную строку UTF-8.

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

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

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

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

Требования

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

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

RtlUTF8ToUnicodeN