Función RtlUTF8StringToUnicodeString (ntifs.h)
La rutina RtlUTF8StringToUnicodeString convierte la cadena UTF-8 especificada en una cadena Unicode.
Sintaxis
NTSYSAPI NTSTATUS RtlUTF8StringToUnicodeString(
PUNICODE_STRING DestinationString,
PUTF8_STRING SourceString,
BOOLEAN AllocateDestinationString
);
Parámetros
DestinationString
Puntero al búfer en el que se almacena la cadena Unicode de salida convertida. El campo DestinationString-MaximumLength> solo se establece si AllocateDestinationString es TRUE.
SourceString
Puntero a la cadena de origen UTF-8 que se va a convertir en Unicode.
AllocateDestinationString
Valor booleano. Cuando se establece TRUE, RtlUTF8StringToUnicodeString asigna el espacio de búfer para la cadena de destino. Esta API asigna solo el almacenamiento para DestinationString-Buffer>. Si RtlUTF8StringToUnicodeString realiza la asignación del búfer, el autor de la llamada debe desasignar el búfer mediante RtlFreeUnicodeString.
Valor devuelto
Esta función devuelve STATUS_SUCCESS cuando la conversión se realiza correctamente. Entre los posibles códigos de error o advertencia se incluyen:
| Código | Descripción |
|---|---|
| STATUS_INVALID_PARAMETERX | Error: uno de los valores de parámetro no es válido. |
| STATUS_NO_MEMORY | Error: RtlUTF8StringToUnicodeString no pudo asignar espacio de búfer. |
| STATUS_BUFFER_OVERFLOW | Advertencia: la cadena convertida en DestinationString-Buffer> se trunca debido a un espacio insuficiente en el búfer de destino. |
| STATUS_SOME_NOT_MAPPED | Advertencia: La llamada se realizó correctamente, pero uno o varios de los caracteres de entrada no eran válidos y fueron convertidos por el carácter de reemplazo Unicode, U+FFFD, antes de convertirse en UTF-8. |
Comentarios
La cadena de salida Unicode solo termina en null si la cadena de entrada UTF-8 está terminada en null.
RtlUTF8StringToUnicodeString 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 carácter válido y se reemplaza por el carácter de reemplazo Unicode, U+FFFD.
RtlUTF8StringToUnicodeString 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 RtlUnicodeStringToUTF8String convierte una cadena Unicode en una cadena UTF-8.
Puede usar las rutinas RtlUTF8StringToUnicodeString y RtlUnicodeStringToUTF8String 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 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 10, versión 2004 |
| Plataforma de destino | Universal |
| Encabezado | ntifs.h (incluya Ntifs.h, Wdm.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| Archivo DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |