Функция RtlUnicodeToUTF8N

  • Статья

Преобразует указанную строку Юникода в новую символьную строку с помощью 8-разрядной кодовой страницы в формате Юникода (UTF-8).

Синтаксис

NTSTATUS WINAPI RtlUnicodeToUTF8N(
  _Out_     PCHAR  UTF8StringDestination,
  _In_      ULONG  UTF8StringMaxByteCount,
  _Out_opt_ PULONG UTF8StringActualByteCount,
  _In_      PCWSTR UnicodeStringSource,
  _In_      ULONG  UnicodeStringByteCount
);

Параметры

UTF8StringDestination [out]

Указатель на буфер, выделенный вызывающим объектом, для получения переведенной строки.

UTF8StringMaxByteCount [in]

Максимальное число байтов, записываемых в UTF8StringDestination. Если это значение приводит к усечению переведенной строки, RtlUnicodeToUTF8N возвращает состояние ошибки.

UTF8StringActualByteCount [out, optional]

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

UnicodeStringSource [in]

Указатель на исходную строку Юникода, которая должна быть преобразована.

*UnicodeStringByteCount * [in]

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

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

RtlUnicodeToUTF8N возвращает одно из следующих значений NTSTATUS:

Код возврата Описание
STATUS_SUCCESS
 Строка Юникода была преобразована в UTF-8.
STATUS_SOME_NOT_MAPPED
 Обнаружен и заменен недопустимый входной символ. Это состояние считается состоянием успешного выполнения.
STATUS_INVALID_PARAMETER
 Оба указателя на UTF8StringDestination и UTF8StringActualByteCount имели значение NULL.
STATUS_INVALID_PARAMETER_4
 UnicodeStringSource имеет значение NULL.
STATUS_BUFFER_TOO_SMALL
 UTF8StringDestination был усечен.

 

Комментарии

Хотя UTF8StringActualByteCount является необязательным и может иметь значение NULL, вызывающие устройства должны предоставить для него хранилище, так как полученную длину можно использовать для определения успешности преобразования. Эта подпрограмма не изменяет исходную строку. Он возвращает строку UTF-8, завершающуюся null, если данный ЮникодStringSource содержал признак конца NULL и если заданное значение UTF8StringMaxByteCount не привело к усечению.

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

Если параметрУ UTF8StringDestination присвоено значение NULL , функция вернет необходимое количество байтов для размещения переведенной строки без усечения в UTF8StringActualByteCount.

Вызывающие функции RtlUnicodeToUTF8N должны выполняться на DISPATCH_LEVEL IRQL < .

Требования

Требование Значение
Минимальная версия клиента
 Windows 7 [только классические приложения]
Минимальная версия сервера
 Windows Server 2008 R2 [только классические приложения]
Заголовок
Wdm.h
DLL
Ntdll.dll

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

RtlUTF8ToUnicodeN