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 que 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 aos quais a rotina foi gravada no buffer que UnicodeStringDestination aponta. Se UnicodeStringDestination não forNULL, 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 à qual o parâmetro UTF8StringSource aponta.

Valor de retorno

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 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 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 ambos NULL.
STATUS_INVALID_PARAMETER_4	O parâmetro UTF8StringSource é NULL.

Observações

A cadeia de caracteres de saída Unicode será encerrada em nulo somente se a cadeia de caracteres de entrada UTF-8 for encerrada 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 caberem no buffer e o valor de UnicodeStringActualByteCount de *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 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 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 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 RtlUTF8ToUnicodeN e RtlUnicodeToUTF8N 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 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

rtlUnicodeToUTF8N