Função RtlUTF8StringToUnicodeString (ntifs.h)

A rotina RtlUTF8StringToUnicodeString converte a cadeia de caracteres UTF-8 especificada em uma cadeia de caracteres Unicode.

Sintaxe

NTSYSAPI NTSTATUS RtlUTF8StringToUnicodeString(
  PUNICODE_STRING DestinationString,
  PUTF8_STRING    SourceString,
  BOOLEAN         AllocateDestinationString
);

Parâmetros

DestinationString

Ponteiro para o buffer no qual a cadeia de caracteres Unicode de saída convertida é armazenada. O campo DestinationString-MaximumLength> será definido somente se AllocateDestinationString for TRUE.

SourceString

Ponteiro para a cadeia de caracteres de origem UTF-8 a ser convertida em Unicode.

AllocateDestinationString

$True. Quando definido TRUE, RtlUTF8StringToUnicodeString aloca o espaço de buffer para a cadeia de caracteres de destino. Somente o armazenamento para DestinationString-Buffer> é alocado por essa API. Se RtlUTF8StringToUnicodeString fizer a alocação de buffer, o chamador deverá desalocar o buffer usando RtlFreeUnicodeString.

Valor retornado

Essa função retorna STATUS_SUCCESS quando a conversão é bem-sucedida. Os possíveis códigos de erro ou aviso incluem:

Código Descrição
STATUS_INVALID_PARAMETERX Erro: um dos valores de parâmetro é inválido.
STATUS_NO_MEMORY Erro: RtlUTF8StringToUnicodeString não pôde alocar espaço em buffer.
STATUS_BUFFER_OVERFLOW Aviso: a cadeia de caracteres convertida em DestinationString-Buffer> é truncada devido ao espaço insuficiente no buffer de destino.
STATUS_SOME_NOT_MAPPED Aviso: a chamada foi bem-sucedida, mas um ou mais dos caracteres de entrada eram inválidos e foram convertidos pelo caractere de substituição Unicode, U+FFFD, antes de serem convertidos em UTF-8.

Comentários

A cadeia de caracteres de saída Unicode será encerrada em nulo somente se a cadeia de caracteres de entrada UTF-8 for encerrada em nulo.

RtlUTF8StringToUnicodeString dá suporte a pares alternativos Unicode. No entanto, um valor de palavra principal alternativo que não é seguido por um valor de palavra à direita ou um valor de palavra à direita que não é precedido por um valor de palavra principal, não é reconhecido como um caractere válido e é substituído pelo caractere de substituição Unicode, U+FFFD.

RtlUTF8StringToUnicodeString continua convertendo a cadeia de caracteres de entrada em uma cadeia de caracteres de saída até chegar ao final do buffer de origem ou ao final do buffer de destino, o que ocorrer primeiro. A rotina converte todos os caracteres nulos na cadeia de caracteres de entrada em caracteres nulos na cadeia de caracteres de saída. Se a cadeia de caracteres de entrada contiver um caractere nulo de terminação, mas o caractere nulo não estiver localizado no final do buffer de origem, a rotina continuará após o caractere nulo de terminação até chegar ao final do espaço de buffer disponível.

A rotina RtlUnicodeStringToUTF8String converte uma cadeia de caracteres Unicode em uma cadeia de caracteres UTF-8.

Você pode usar as rotinas RtlUTF8StringToUnicodeString e RtlUnicodeStringToUTF8String para executar uma conversão sem perdas de cadeias de texto válidas entre os formatos UTF-8 e Unicode. No entanto, cadeias de caracteres que têm valores de dados arbitrários provavelmente violarão as regras Unicode para codificar pares substitutos, e qualquer informação contida nos valores inválidos em uma cadeia de caracteres de entrada é perdida e não pode ser recuperada da cadeia de caracteres de saída resultante.

Requisitos

   
Cliente mínimo com suporte Windows 10, versão 2004
Plataforma de Destino Universal
Cabeçalho ntifs.h (incluem Ntifs.h, Wdm.h, Ntifs.h)
Biblioteca NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

Confira também

RtlFreeUnicodeString

RtlUnicodeStringToUTF8String