Función RtlUnicodeToUTF8N (ntifs.h)
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 apunta UTF8StringDestination . 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 apunta UTF8StringDestination . Si UTF8StringDestination no es NULL, 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 se realiza correctamente 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 se realiza correctamente, 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 |
|---|---|
|
El parámetro UTF8StringMaxByteCount especifica un tamaño de búfer demasiado pequeño para contener toda la cadena de salida. |
|
Los parámetros UTF8StringDestination y UTF8StringActualByteCount son NULL. |
|
El parámetro UnicodeStringSource es NULL. |
|
UnicodeStringByteCount no es un entero múltiplo de sizeof(WCHAR). |
Comentarios
La cadena de salida UTF-8 solo termina en null si la cadena de entrada Unicode termina 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 de nuevo 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 está 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 llega 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 las rutinas RtlUnicodeToUTF8N y RtlUTF8ToUnicode 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 tienen 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 | Value |
|---|---|
| Cliente mínimo compatible | Windows 7 |
| Plataforma de destino | Universal |
| Encabezado | ntifs.h (incluya Ntifs.h, Wdm.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| Archivo DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |