Función RtlAnsiStringToUnicodeString (wdm.h)

Artículo
02/27/2024

RtlAnsiStringToUnicodeString convierte la cadena de origen ANSI especificada en una cadena Unicode.

Sintaxis

NTSYSAPI NTSTATUS RtlAnsiStringToUnicodeString(
  [in, out] PUNICODE_STRING DestinationString,
  [in]      PCANSI_STRING   SourceString,
  [in]      BOOLEAN         AllocateDestinationString
);

Parámetros

[in, out] DestinationString

Puntero a una estructura UNICODE_STRING que contiene la cadena Unicode convertida. Si AllocateDestinationString es TRUE, la rutina asigna un nuevo búfer para contener los datos de cadena y actualiza el miembro Buffer de DestinationString para que apunte al nuevo búfer. De lo contrario, la rutina usa el búfer especificado actualmente para contener la cadena.

[in] SourceString

Puntero a la cadena ANSI que se va a convertir en Unicode.

[in] AllocateDestinationString

Especifica si esta rutina debe asignar el espacio de búfer para la cadena de destino. Si es así, el autor de la llamada debe desasignar el búfer llamando a RtlFreeUnicodeString.

Valor devuelto

Si la conversión se realiza correctamente, RtlAnsiStringToUnicodeString devuelve STATUS_SUCCESS. En caso de error, la rutina no asigna ninguna memoria.

Comentarios

La traducción se ajusta a la información de configuración regional del sistema actual.

Si el llamador establece AllocateDestinationString en TRUE, la rutina reemplaza el miembro Buffer de DestinationString por un puntero al búfer que asigna. El valor anterior se puede sobrescribir incluso cuando la rutina devuelve un código de estado de error.

Esta rutina no se declara en un archivo de encabezado. Sin embargo, puede copiar la siguiente declaración en el código fuente:

NTSYSAPI
WCHAR
NTAPI
RtlAnsiCharToUnicodeChar(
    __inout PUCHAR *SourceCharacter
    );

Puede usar las siguientes rutinas para convertir caracteres de un solo byte y de doble byte en caracteres Unicode:

Para obtener más información sobre estas y otras rutinas de control de cadenas, vea Rutinas de la biblioteca en tiempo de ejecución (RTL).

RtlAnsiCharToUnicodeChar tiene deficiencias de seguridad. Considere la posibilidad de usar la rutina RtlAnsiStringToUnicodeString en su lugar.

Si, en la entrada, *SourceCharacter apunta a un búfer de un byte que contiene el primer byte de un código de carácter de dos bytes, RtlAnsiCharToUnicodeChar sobreeje el búfer cuando intenta leer el segundo byte.

Al iniciar el sistema, el sistema operativo determina el idioma del usuario de la configuración regional e instala la página de códigos ANSI del sistema adecuada. RtlAnsiCharToUnicodeChar usa esta página de códigos para convertir un carácter de un solo byte o de doble byte en el carácter Unicode correspondiente.

Si la página de códigos ANSI del sistema define un juego de caracteres de un solo byte (es decir, el juego de caracteres ANSI), RtlAnsiCharToUnicodeChar acelera la operación de conversión simplemente extendiendo cero un carácter ANSI en el intervalo 0x00 a 0x7f para generar el carácter Unicode correspondiente. La rutina convierte el valor ANSI 0x5c en el carácter de barra diagonal inversa ("\"), incluso si la página de códigos de un solo byte define este carácter como signo de yen.

Si, en la entrada, *SourceCharacter apunta a un código de caracteres no válido, RtlAnsiCharToUnicodeChar devuelve el código de caracteres de espacio Unicode, 0x0020. En la lista siguiente se muestran ejemplos de códigos de caracteres no válidos:

El primer byte del código de caracteres es un valor que solo es válido como el segundo byte de un código de caracteres de dos bytes.
El segundo byte de un código de caracteres de dos bytes es un valor que solo es válido como primer byte.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL