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 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:

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

Confira também

RtlFreeUnicodeString

RtlUnicodeStringToUTF8String