Поделиться через


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

Подпрограмма 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

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

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

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
Параметр ЮникодStringSourceNULL.
STATUS_INVALID_PARAMETER_5
ЮникодStringByteCount не является целым числом размера(WCHAR).

Замечания

Выходная строка UTF-8 завершается null, только если входная строка Юникода завершается null.

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

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

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

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

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

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

Требования

Требование Ценность
минимальные поддерживаемые клиентские Windows 7
целевая платформа Всеобщий
заголовка ntifs.h (include Ntifs.h, Wdm.h, Ntifs.h)
библиотеки NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

См. также

RtlUTF8ToUnicodeN