Função RtlUnicodeToUTF8N (ntifs.h)

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 para os quais 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 gravados no buffer para o qual UTF8StringDestination aponta. Se UTF8StringDestination não for NULL, 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 para a qual o parâmetro UnicodeStringSource aponta.

Retornar valor

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 caracteres 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 possíveis valores retornados por erro 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 NULL.
STATUS_INVALID_PARAMETER_4	O parâmetro UnicodeStringSource é NULL.
STATUS_INVALID_PARAMETER_5	UnicodeStringByteCount não é um número inteiro múltiplo de sizeof (WCHAR).

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.

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 caberão no buffer e o valor *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 terminação.

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

RtlUnicodeToUTF8N continua a converter 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 as rotinas RtlUnicodeToUTF8N e RtlUTF8ToUnicode 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 são perdidas e não podem ser recuperadas da cadeia de caracteres de saída resultante.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 7
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

RtlUTF8ToUnicodeN