Функция RtlUTF8ToUnicodeN

  • Статья

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

Синтаксис

NTSTATUS WINAPI RtlUTF8ToUnicodeN(
  _Out_     PWSTR  UnicodeStringDestination,
  _In_      ULONG  UnicodeStringMaxByteCount,
  _Out_opt_ PULONG UnicodeStringActualByteCount,
  _In_      PCCH   UTF8StringSource,
  _In_      ULONG  UTF8StringByteCount
);

Параметры

UnicodeStringDestination [out]

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

UnicodeStringMaxByteCount [in]

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

UnicodeStringActualByteCount [out, optional]

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

UTF8StringSource [in]

Указатель на строку для перевода.

UTF8StringByteCount [in]

Размер строки в байтах в UTF8StringSource.

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

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

Код возврата Описание
STATUS_SUCCESS
 Строка была преобразована в Юникод.
STATUS_SOME_NOT_MAPPED
 Обнаружен и заменен недопустимый входной символ. Это состояние считается состоянием успешного выполнения.
STATUS_INVALID_PARAMETER
 Оба указателя на UnicodeStringDestination и UnicodeStringActualByteCount имели значение NULL.
STATUS_INVALID_PARAMETER_4
 UTF8StringSource имеет значение NULL.
STATUS_BUFFER_TOO_SMALL
 ЮникодStringDestination был усечен.

 

Комментарии

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

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

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

RtlUTF8ToUnicodeN не изменяет исходную строку, если только указатели UnicodeStringDestination и UTF8StringSource не эквивалентны. Возвращаемая строка Юникода не завершается null.

Вызывающие объект RtlUTF8ToUnicodeN должны выполняться на DISPATCH_LEVEL IRQL < .

Требования

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

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

RtlUnicodeToUTF8N