Função RtlUTF8ToUnicodeN (ntifs.h)

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

Sintaxe

NTSYSAPI NTSTATUS RtlUTF8ToUnicodeN(
  [out, optional] PWSTR  UnicodeStringDestination,
  [in]            ULONG  UnicodeStringMaxByteCount,
  [out]           PULONG UnicodeStringActualByteCount,
  [in]            PCCH   UTF8StringSource,
  [in]            ULONG  UTF8StringByteCount
);

Parâmetros

[out, optional] UnicodeStringDestination

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

[in] UnicodeStringMaxByteCount

Especifica o número máximo de bytes para os quais a rotina pode gravar no buffer para o qual UnicodeStringDestination aponta. Se UnicodeStringDestination = NULL, defina UnicodeStringMaxByteCount = 0.

[out] UnicodeStringActualByteCount

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

[in] UTF8StringSource

Um ponteiro para a cadeia de caracteres de origem UTF-8.

[in] UTF8StringByteCount

Especifica o número de bytes na cadeia de caracteres de origem UTF-8 para a qual o parâmetro UTF8StringSource aponta.

Retornar valor

RtlUTF8ToUnicodeN retornará STATUS_SUCCESS se a chamada for bem-sucedida e todos os códigos de caractere UTF-8 na cadeia de caracteres de entrada forem convertidos nos códigos de caractere Unicode 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 convertidos no caractere de substituição Unicode, U+FFFD. 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 UnicodeStringMaxByteCount especifica um tamanho de buffer muito pequeno para conter toda a cadeia de caracteres de saída.
STATUS_INVALID_PARAMETER	Os parâmetros UnicodeStringDestination e UnicodeStringActualByteCount são NULL.
STATUS_INVALID_PARAMETER_4	O parâmetro UTF8StringSource é NULL.

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.

A rotina retornará STATUS_BUFFER_TOO_SMALL se o parâmetro UnicodeStringMaxByteCount especificar um tamanho de buffer muito pequeno para conter toda a cadeia de caracteres de saída. Nesse caso, a rotina grava quantos caracteres Unicode caberão no buffer e o valor *UnicodeStringActualByteCount 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 RtlUTF8ToUnicodeN para obter o tamanho do buffer de saída necessário e, em seguida, chamar RtlUTF8ToUnicodeN novamente para obter a cadeia de caracteres de saída Unicode. Na chamada inicial, defina UnicodeStringDestination = NULL e UnicodeStringMaxByteCount = 0 e a rotina gravará o tamanho do buffer necessário em *UnicodeStringActualByteCount. Em seguida, aloque um buffer do tamanho necessário e chame RtlUTF8ToUnicodeN uma segunda vez para obter a cadeia de caracteres de saída Unicode.

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

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

Você pode usar as rotinas RtlUTF8ToUnicode e RtlUnicodeToUTF8N para executar uma conversão sem perda 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 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

RtlUnicodeToUTF8N