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

Статья
11/08/2024

Подпрограмма 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, подпрограмма записывает требуемый размер выходного буфера в *ЮникодStringActingByteCount.

[in] UnicodeStringMaxByteCount

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

[out] UnicodeStringActualByteCount

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

[in] UTF8StringSource

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

[in] UTF8StringByteCount

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

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

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

Возвращаемый код	Описание
STATUS_BUFFER_TOO_SMALL	Параметр ЮникодStringMaxByteCount указывает размер буфера, который слишком мал, чтобы содержать всю выходную строку.
STATUS_INVALID_PARAMETER	Параметры ЮникодStringDestination и параметров UnicodeStringActingByteCount являются NULL.
STATUS_INVALID_PARAMETER_4	Параметр UTF8StringSourceNULL.

Замечания

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

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

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

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

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

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

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

Требования

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

См. также

RtlUnicodeToUTF8N

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