Função RtlAnsiStringToUnicodeString (wdm.h)

Artigo
03/08/2023

RtlAnsiStringToUnicodeString converte a cadeia de caracteres de origem ANSI fornecida em uma cadeia de caracteres Unicode.

Sintaxe

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

Parâmetros

[in, out] DestinationString

Ponteiro para uma estrutura UNICODE_STRING para manter a cadeia de caracteres Unicode convertida. Se AllocateDestinationString for TRUE, a rotina alocará um novo buffer para manter os dados da cadeia de caracteres e atualizará o membro Buffer de DestinationString para apontar para o novo buffer. Caso contrário, a rotina usa o buffer especificado no momento para manter a cadeia de caracteres.

[in] SourceString

Ponteiro para a cadeia de caracteres ANSI a ser convertida em Unicode.

[in] AllocateDestinationString

Especifica se essa rotina deve alocar o espaço de buffer para a cadeia de caracteres de destino. Se isso acontecer, o chamador deverá desalocar o buffer chamando RtlFreeUnicodeString.

Retornar valor

Se a conversão for bem-sucedida, RtlAnsiStringToUnicodeString retornará STATUS_SUCCESS. Em caso de falha, a rotina não aloca nenhuma memória.

Comentários

A tradução está em conformidade com as informações atuais de localidade do sistema.

Se o chamador definir AllocateDestinationString como TRUE, a rotina substituirá o membro Buffer de DestinationString por um ponteiro para o buffer alocado. O valor antigo pode ser substituído mesmo quando a rotina retorna um erro status código.

Essa rotina não é declarada em um arquivo de cabeçalho. No entanto, você pode copiar a seguinte declaração para o código-fonte:

NTSYSAPI
WCHAR
NTAPI
RtlAnsiCharToUnicodeChar(
    __inout PUCHAR *SourceCharacter
    );

Você pode usar as seguintes rotinas para converter caracteres de byte único e byte duplo em caracteres Unicode:

Para obter mais informações sobre essas e outras rotinas de manipulação de cadeia de caracteres, consulte Rotinas de RTL (Biblioteca em Tempo de Execução).

RtlAnsiCharToUnicodeChar tem deficiências de segurança. Considere usar a rotina RtlAnsiStringToUnicodeString .

Se, na entrada, *SourceCharacter apontar para um buffer de um byte que contém o primeiro byte de um código de caracteres de dois bytes, RtlAnsiCharToUnicodeChar ultrapassará o buffer quando tentar ler o segundo byte.

Na inicialização do sistema, o sistema operacional determina o idioma do usuário das configurações de localidade e instala a página de código ANSI do sistema apropriada. RtlAnsiCharToUnicodeChar usa esta página de código para converter um caractere de byte único ou de byte duplo no caractere Unicode correspondente.

Se a página de código ANSI do sistema definir um conjunto de caracteres de byte único (ou seja, o conjunto de caracteres ANSI), RtlAnsiCharToUnicodeChar acelerará a operação de conversão simplesmente estendendo zero um caractere ANSI no intervalo 0x00 para 0x7f para produzir o caractere Unicode correspondente. A rotina converte o valor ANSI 0x5c para o caractere de barra invertida ("\"), mesmo que a página de código de byte único defina esse caractere como o sinal de iene.

Se, na entrada, *SourceCharacter apontar para um código de caractere inválido, RtlAnsiCharToUnicodeChar retornará o código de caractere de espaço Unicode 0x0020. A lista a seguir mostra exemplos de códigos de caractere inválidos:

O primeiro byte do código de caractere é um valor válido apenas como o segundo byte de um código de caracteres de dois bytes.
O segundo byte de um código de caractere de dois bytes é um valor válido apenas como o primeiro byte.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL