Función RtlUnicodeToUTF8N (ntifs.h)

Artículo
11/08/2024

La rutina RtlUnicodeToUTF8N convierte una cadena Unicode en una cadena UTF-8.

Sintaxis

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

Parámetros

[out] UTF8StringDestination

Puntero a un búfer de destino asignado por el autor de la llamada en el que la rutina escribe la cadena de salida UTF-8. Si este parámetro es NULL, la rutina escribe el tamaño necesario del búfer de salida en *UTF8StringActualByteCount.

[in] UTF8StringMaxByteCount

Especifica el número máximo de bytes a los que la rutina puede escribir en el búfer al que UTF8StringDestination apunta. Si UTF8StringDestination = null, establezca UTF8StringMaxByteCount = 0.

[out] UTF8StringActualByteCount

Puntero a una ubicación en la que la rutina escribe el número real de bytes que ha escrito en el búfer al que UTF8StringDestination apunta. Si UTF8StringDestination no esNULL, este recuento nunca supera el valor de UTF8StringMaxByteCount. Si UTF8StringDestination es NULL, este recuento es el número de bytes necesarios para contener toda la cadena de salida.

[in] UnicodeStringSource

Puntero a la cadena de origen Unicode.

[in] UnicodeStringByteCount

Especifica el número de bytes de la cadena de origen Unicode a la que apunta el parámetro UnicodeStringSource.

Valor devuelto

rtlUnicodeToUTF8N devuelve STATUS_SUCCESS si la llamada es correcta y todos los códigos de caracteres Unicode de la cadena de entrada se convirtieron en los códigos de caracteres UTF-8 correspondientes de la cadena de salida. Devuelve STATUS_SOME_NOT_MAPPED si la llamada es correcta, pero uno o varios caracteres de entrada no eran válidos y se reemplazaron por el carácter de reemplazo Unicode, U+FFFD, antes de que se convirtieran en UTF-8. Entre los posibles valores devueltos de error se incluyen los siguientes códigos de error:

Código devuelto	Descripción
STATUS_BUFFER_TOO_SMALL	El parámetro UTF8StringMaxByteCount especifica un tamaño de búfer demasiado pequeño para contener toda la cadena de salida.
STATUS_INVALID_PARAMETER	Los de de UTF8StringDestination y parámetros UTF8StringActualByteCount son null.
STATUS_INVALID_PARAMETER_4	El parámetro unicodeStringSource es NULL.
STATUS_INVALID_PARAMETER_5	UnicodeStringByteCount no es un entero múltiplo de tamaño de(WCHAR).

Observaciones

La cadena de salida UTF-8 solo termina en null si la cadena de entrada Unicode está terminada en null.

La rutina devuelve STATUS_BUFFER_TOO_SMALL si el parámetro UTF8StringMaxByteCount especifica un tamaño de búfer demasiado pequeño para contener toda la cadena de salida. En este caso, la rutina escribe tantos caracteres UTF-8 como caberán en el búfer y el valor *UTF8StringActualByteCount especifica el número de bytes válidos que la rutina ha escrito en el búfer. Es posible que la cadena parcial contenida en el búfer de salida no incluya un carácter NULO de terminación.

Puede realizar una llamada inicial a rtlUnicodeToUTF8N para obtener el tamaño de búfer de salida necesario y, a continuación, llamar a RtlUnicodeToUTF8N para obtener la cadena de salida Unicode. En la llamada inicial, establezca UTF8StringDestination = NULL y UTF8StringMaxByteCount = 0 y la rutina escribirá el tamaño de búfer necesario en *UTF8StringActualByteCount. A continuación, asigne un búfer del tamaño necesario y llame a RtlUnicodeToUTF8N una segunda vez para obtener la cadena de salida UTF-8.

rtlUnicodeToUTF8N admite pares suplentes Unicode. Sin embargo, un valor de palabra inicial suplente que no va seguido de un valor de palabra final, o un valor de palabra final que no va precedido por un valor de palabra inicial, no se reconoce como un código de carácter válido y se reemplaza por el carácter de reemplazo Unicode, U+FFFD.

rtlUnicodeToUTF8N continúa convirtiendo la cadena de entrada en una cadena de salida hasta que llegue al final del búfer de origen o al final del búfer de destino, lo que ocurra primero. La rutina convierte los caracteres NULL de la cadena de entrada en caracteres NULL en la cadena de salida. Si la cadena de entrada contiene un carácter NULO de terminación, pero el carácter NULL no se encuentra al final del búfer de origen, la rutina continúa después del carácter NULO de terminación hasta que llega al final del espacio de búfer disponible.

La rutina RtlUTF8ToUnicodeN convierte una cadena UTF-8 en una cadena Unicode.

Puede usar rutinas de RtlUnicodeToUTF8N y RtlUTF8ToUnicodeN para realizar una conversión sin pérdida de cadenas de texto válidas entre los formatos Unicode y UTF-8. Sin embargo, es probable que las cadenas que tengan valores de datos arbitrarios infrinjan las reglas Unicode para codificar pares suplentes, y cualquier información contenida en los valores no válidos de una cadena de entrada se pierde y no se puede recuperar de la cadena de salida resultante.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 7
de la plataforma de destino de	Universal
encabezado de	ntifs.h (include Ntifs.h, Wdm.h, Ntifs.h)
biblioteca de	NtosKrnl.lib
DLL de	NtosKrnl.exe
irQL	PASSIVE_LEVEL

Consulte también

rtlUTF8ToUnicodeN

Compartir a través de