Função RtlUTF8StringToUnicodeString (ntifs.h)

  • Artigo

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 COMO 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.

Retornar valor

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 a 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á terminada em nulo somente se a cadeia de caracteres de entrada UTF-8 for terminada em nulo.

RtlUTF8StringToUnicodeString dá suporte a pares alternativos Unicode. No entanto, um valor de palavra à esquerda 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 à esquerda, 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 caracteres 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 quaisquer informações contidas nos valores inválidos em uma cadeia de caracteres de entrada serão perdidas e não poderão ser recuperadas da cadeia de caracteres de saída resultante.

Requisitos

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

Confira também

RtlFreeUnicodeString

RtlUnicodeStringToUTF8String