Função RtlUnicodeToUTF8N (ntifs.h)

Artigo
11/08/2024

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

Sintaxe

NTSYSAPI NTSTATUS RtlUnicodeToUTF8N(
  [out] PCHAR  UTF8StringDestination,
  [in]  ULONG  UTF8StringMaxByteCount,
  [out] PULONG UTF8StringActualByteCount,
  [in]  PCWCH  UnicodeStringSource,
  [in]  ULONG  UnicodeStringByteCount
);

Parâmetros

[out] UTF8StringDestination

Um ponteiro para um buffer de destino alocado pelo chamador no qual a rotina grava a cadeia de caracteres de saída UTF-8. Se esse parâmetro for NULL, a rotina gravará o tamanho necessário do buffer de saída em *UTF8StringActualByteCount.

[in] UTF8StringMaxByteCount

Especifica o número máximo de bytes que a rotina pode gravar no buffer para o qual UTF8StringDestination aponta. Se UTF8StringDestination = NULL, defina UTF8StringMaxByteCount = 0.

[out] UTF8StringActualByteCount

Um ponteiro para um local no qual a rotina grava o número real de bytes que ele gravou no buffer para o qual UTF8StringDestination aponta. Se UTF8StringDestination não forNULL, essa contagem nunca excederá o valor de UTF8StringMaxByteCount. Se UTF8StringDestination for NULL, essa contagem será o número de bytes necessários para conter toda a cadeia de caracteres de saída.

[in] UnicodeStringSource

Um ponteiro para a cadeia de caracteres de origem Unicode.

[in] UnicodeStringByteCount

Especifica o número de bytes na cadeia de caracteres de origem Unicode à qual o parâmetro UnicodeStringSource aponta.

Valor de retorno

RtlUnicodeToUTF8N retornará STATUS_SUCCESS se a chamada for bem-sucedida e todos os códigos de caractere Unicode na cadeia de caracteres de entrada forem convertidos nos códigos de caractere UTF-8 correspondentes na cadeia de caracteres de saída. Ele retornará STATUS_SOME_NOT_MAPPED se a chamada for bem-sucedida, mas um ou mais caracteres de entrada forem inválidos e forem substituídos pelo caractere de substituição Unicode, U+FFFD, antes de serem convertidos em UTF-8. Os valores de retorno de erro possíveis incluem os seguintes códigos de erro:

Código de retorno	Descrição
STATUS_BUFFER_TOO_SMALL	O parâmetro UTF8StringMaxByteCount especifica um tamanho de buffer muito pequeno para conter toda a cadeia de caracteres de saída.
STATUS_INVALID_PARAMETER	Os parâmetros UTF8StringDestination e UTF8StringActualByteCount são ambos NULL.
STATUS_INVALID_PARAMETER_4	O parâmetro UnicodeStringSource é NULL.
STATUS_INVALID_PARAMETER_5	UnicodeStringByteCount não é um múltiplo inteiro de tamanhos de(WCHAR).

Observações

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

A rotina retornará STATUS_BUFFER_TOO_SMALL se o parâmetro UTF8StringMaxByteCount especificar um tamanho de buffer muito pequeno para conter toda a cadeia de caracteres de saída. Nesse caso, a rotina grava quantos caracteres UTF-8 caberem no buffer, e o valor de *UTF8StringActualByteCount especifica o número de bytes válidos que a rotina gravou no buffer. A cadeia de caracteres parcial contida no buffer de saída pode não incluir um caractere nulo de encerramento.

Você pode fazer uma chamada inicial para RtlUnicodeToUTF8N para obter o tamanho do buffer de saída necessário e, em seguida, chamar RtlUnicodeToUTF8N novamente para obter a cadeia de caracteres de saída Unicode. Na chamada inicial, defina UTF8StringDestination = NULL e UTF8StringMaxByteCount = 0 e a rotina gravará o tamanho do buffer necessário em *UTF8StringActualByteCount. Em seguida, aloque um buffer do tamanho necessário e chame RtlUnicodeToUTF8N uma segunda vez para obter a cadeia de caracteres de saída UTF-8.

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

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

Você pode usar rtlUnicodeToUTF8N e rtlUTF8ToUnicodeN rotinas para executar uma conversão sem perdas de cadeias 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 qualquer informação contida nos valores inválidos em uma cadeia de caracteres de entrada será perdida e não poderá ser recuperada da cadeia de caracteres de saída resultante.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 7
da Plataforma de Destino	Universal
cabeçalho	ntifs.h (incluem Ntifs.h, Wdm.h, Ntifs.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

Consulte também

RtlUTF8ToUnicodeN

Partilhar via