Função RtlUnicodeStringToUTF8String (ntifs.h)

RtlUnicodeStringToUTF8String converte a cadeia de caracteres Unicode especificada em uma cadeia de caracteres UTF-8.

Sintaxe

NTSYSAPI NTSTATUS RtlUnicodeStringToUTF8String(
  PUTF8_STRING     DestinationString,
  PCUNICODE_STRING SourceString,
  BOOLEAN          AllocateDestinationString
);

Parâmetros

DestinationString

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

SourceString

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

AllocateDestinationString

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

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: RtlUnicodeStringToUTF8String 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 substituídos pelo caractere de substituição Unicode, U+FFFD, antes de serem convertidos em UTF-8.

Comentários

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

RtlUnicodeStringToUTF8String 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 código de caractere válido e é substituído pelo caractere de substituição Unicode, U+FFFD.

RtlUnicodeStringToUTF8String 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 RtlUTF8StringToUnicodeString converte uma cadeia de caracteres UTF-8 em uma cadeia de caracteres Unicode.

Você pode usar as rotinas RtlUnicodeStringToUTF8String e RtlUTF8StringToUnicodeString para executar uma conversão sem perdas de cadeias de caracteres de texto válidas entre os formatos Unicode e UTF-8. 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
Cabeçalho	ntifs.h

Confira também

RtlFreeUTF8String

RtlUTF8StringToUnicodeString