Función RtlUnicodeStringToUTF8String (ntifs.h)
RtlUnicodeStringToUTF8String convierte la cadena Unicode especificada en una cadena UTF-8.
Sintaxis
NTSYSAPI NTSTATUS RtlUnicodeStringToUTF8String(
PUTF8_STRING DestinationString,
PCUNICODE_STRING SourceString,
BOOLEAN AllocateDestinationString
);
Parámetros
DestinationString
Puntero al búfer en el que se coloca la cadena UTF-8 de salida convertida. El campo DestinationString-MaximumLength> solo se establece si AllocateDestinationString es TRUE.
SourceString
Puntero a la cadena Unicode que se va a convertir en UTF-8.
AllocateDestinationString
Valor booleano. Cuando se establece TRUE, RtlUnicodeStringToUTF8String asigna el espacio de búfer para la cadena de destino. Esta API asigna solo el almacenamiento para DestinationString-Buffer>. Si RtlUnicodeStringToUTF8String realiza la asignación del búfer, el autor de la llamada debe desasignar el búfer mediante RtlFreeUTF8String.
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: RtlUnicodeStringToUTF8String 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 se reemplazaron por el carácter de reemplazo Unicode, U+FFFD, antes de convertirse en UTF-8. |
Comentarios
La cadena de salida UTF-8 solo termina en null si la cadena de entrada Unicode termina en null.
RtlUnicodeStringToUTF8String 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.
RtlUnicodeStringToUTF8String 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 RtlUTF8StringToUnicodeString convierte una cadena UTF-8 en una cadena Unicode.
Puede usar las rutinas RtlUnicodeStringToUTF8String y RtlUTF8StringToUnicodeString 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 10, versión 2004 |
| Encabezado | ntifs.h |