Compartir a través de

Función RtlUnicodeToUTF8N

  • Artículo

Convierte la cadena Unicode especificada en una nueva cadena de caracteres mediante la página de códigos Formato de transformación Unicode de 8 bits (UTF-8).

Sintaxis

NTSTATUS WINAPI RtlUnicodeToUTF8N(
  _Out_     PCHAR  UTF8StringDestination,
  _In_      ULONG  UTF8StringMaxByteCount,
  _Out_opt_ PULONG UTF8StringActualByteCount,
  _In_      PCWSTR UnicodeStringSource,
  _In_      ULONG  UnicodeStringByteCount
);

Parámetros

UTF8StringDestination [out]

Puntero a un búfer asignado por el autor de la llamada para recibir la cadena traducida.

UTF8StringMaxByteCount [in]

Número máximo de bytes que se van a escribir en UTF8StringDestination. Si este valor hace que la cadena traducida se trunque, RtlUnicodeToUTF8N devuelve un estado de error.

UTF8StringActualByteCount [out, opcional]

Puntero a una variable asignada por el autor de la llamada que recibe la longitud, en bytes, de la cadena traducida. Este parámetro es opcional y puede ser NULL. Si la cadena se trunca, el número devuelto cuenta el número truncado real.

UnicodeStringSource [in]

Puntero a la cadena de origen Unicode que se va a traducir.

*UnicodeStringByteCount * [in]

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

Valor devuelto

RtlUnicodeToUTF8N devuelve uno de los siguientes valores NTSTATUS:

Código devuelto Descripción
STATUS_SUCCESS
 La cadena Unicode se convirtió en UTF-8.
STATUS_SOME_NOT_MAPPED
 Se encontró un carácter de entrada no válido y se reemplazó. Este estado se considera un estado correcto.
STATUS_INVALID_PARAMETER
 Ambos punteros a UTF8StringDestination y UTF8StringActualByteCount eran NULL.
STATUS_INVALID_PARAMETER_4
 UnicodeStringSource era NULL.
STATUS_BUFFER_TOO_SMALL
 Se trunca la UTF8StringDestination.

 

Comentarios

Aunque UTF8StringActualByteCount es opcional y puede ser NULL, los autores de llamadas deben proporcionar almacenamiento para él, ya que la longitud recibida se puede usar para determinar si la conversión se realizó correctamente. Esta rutina no modifica la cadena de origen. Devuelve una cadena UTF-8 terminada en null si el objeto UnicodeStringSource determinado incluía un terminador NULL y si el UTF8StringMaxByteCount dado no provocó el truncamiento.

Si la salida se trunca y se encuentra un carácter de entrada no válido, la función devuelve STATUS_BUFFER_TOO_SMALL error.

Si UTF8StringDestination se establece en NULL , la función devolverá el número necesario de bytes para hospedar la cadena traducida sin truncamiento en UTF8StringActualByteCount.

Los autores de llamadas de RtlUnicodeToUTF8N deben ejecutarse en irQL < DISPATCH_LEVEL.

Requisitos

Requisito Value
Cliente mínimo compatible
 Windows 7 [solo aplicaciones de escritorio]
Servidor mínimo compatible
 Windows Server 2008 R2 [solo aplicaciones de escritorio]
Encabezado
Wdm.h
Archivo DLL
Ntdll.dll

Consulte también

RtlUTF8ToUnicodeN