Función RtlUTF8ToUnicodeN (ntifs.h)

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

Sintaxis

NTSYSAPI NTSTATUS RtlUTF8ToUnicodeN(
  [out, optional] PWSTR  UnicodeStringDestination,
  [in]            ULONG  UnicodeStringMaxByteCount,
  [out]           PULONG UnicodeStringActualByteCount,
  [in]            PCCH   UTF8StringSource,
  [in]            ULONG  UTF8StringByteCount
);

Parámetros

[out, optional] UnicodeStringDestination

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

[in] UnicodeStringMaxByteCount

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

[out] UnicodeStringActualByteCount

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

[in] UTF8StringSource

Puntero a la cadena de origen UTF-8.

[in] UTF8StringByteCount

Especifica el número de bytes de la cadena de origen UTF-8 a la que apunta el parámetro UTF8StringSource.

Valor devuelto

rtlUTF8ToUnicodeN devuelve STATUS_SUCCESS si la llamada es correcta y todos los códigos de caracteres UTF-8 de la cadena de entrada se convirtieron en los códigos de caracteres Unicode correspondientes de la cadena de salida. Devuelve STATUS_SOME_NOT_MAPPED si la llamada se realiza correctamente, pero uno o varios caracteres de entrada no eran válidos y se convirtieron en el carácter de reemplazo Unicode, U+FFFD. 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 UnicodeStringMaxByteCount especifica un tamaño de búfer demasiado pequeño para contener toda la cadena de salida.
STATUS_INVALID_PARAMETER	El de UnicodeStringDestination y parámetros UnicodeStringActingActualByteCount son NULL.
STATUS_INVALID_PARAMETER_4	El parámetro UTF8StringSource es NULL.

Observaciones

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

La rutina devuelve STATUS_BUFFER_TOO_SMALL si el parámetro UnicodeStringMaxByteCount 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 Unicode como caberán en el búfer y el valor *UnicodeStringActualByteCount 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 rtlUTF8ToUnicodeN para obtener el tamaño de búfer de salida necesario y, a continuación, llamar a RtlUTF8ToUnicodeN para obtener la cadena de salida Unicode. En la llamada inicial, establezca UnicodeStringDestination = NULL y UnicodeStringMaxByteCount = 0 y la rutina escribirá el tamaño de búfer necesario en *UnicodeStringActualByteCount. A continuación, asigne un búfer del tamaño necesario y llame a RtlUTF8ToUnicodeN una segunda vez para obtener la cadena de salida Unicode.

RtlUTF8ToUnicodeN 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 carácter válido y se reemplaza por el carácter de reemplazo Unicode, U+FFFD.

RtlUTF8ToUnicodeN 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 RtlUnicodeToUTF8N convierte una cadena Unicode en una cadena UTF-8.

Puede usar las rutinas de RtlUTF8ToUnicodeN y RtlUnicodeToUTF8N para realizar una conversión sin pérdida de cadenas de texto válidas entre los formatos UTF-8 y Unicode. 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

RtlUnicodeToUTF8N