Função RtlUnicodeToUTF8N
Converte a cadeia de caracteres Unicode especificada em uma nova cadeia de caracteres, usando a página de código UTF-8 (Formato de Transformação Unicode) de 8 bits.
Sintaxe
NTSTATUS WINAPI RtlUnicodeToUTF8N(
_Out_ PCHAR UTF8StringDestination,
_In_ ULONG UTF8StringMaxByteCount,
_Out_opt_ PULONG UTF8StringActualByteCount,
_In_ PCWSTR UnicodeStringSource,
_In_ ULONG UnicodeStringByteCount
);
Parâmetros
-
UTF8StringDestination [out]
-
Um ponteiro para um buffer alocado pelo chamador para receber a cadeia de caracteres traduzida.
-
UTF8StringMaxByteCount [in]
-
Número máximo de bytes a serem gravados em UTF8StringDestination. Se esse valor fizer com que a cadeia de caracteres traduzida seja truncada, RtlUnicodeToUTF8N retornará um erro status.
-
UTF8StringActualByteCount [out, opcional]
-
Um ponteiro para uma variável alocada pelo chamador que recebe o comprimento, em bytes, da cadeia de caracteres traduzida. Esse parâmetro é opcional e pode ser NULL. Se a cadeia de caracteres for truncada, o número retornado conta a contagem real de cadeias de caracteres truncadas.
-
UnicodeStringSource [in]
-
Um ponteiro para a cadeia de caracteres de origem Unicode a ser convertida.
-
*UnicodeStringByteCount * [in]
-
Especifica o número de bytes na cadeia de caracteres de origem Unicode para a qual o parâmetro UnicodeStringSource aponta.
Valor retornado
RtlUnicodeToUTF8N retorna um dos seguintes valores NTSTATUS:
| Código de retorno | Descrição |
|---|---|
|
A cadeia de caracteres Unicode foi convertida em UTF-8. |
|
Um caractere de entrada inválido foi encontrado e substituído. Este status é considerado um status de sucesso. |
|
Ambos os ponteiros para UTF8StringDestination e UTF8StringActualByteCount eram NULL. |
|
O UnicodeStringSource era NULL. |
|
UTF8StringDestination foi truncado. |
Comentários
Embora UTF8StringActualByteCount seja opcional e possa ser NULL, os chamadores devem fornecer armazenamento para ele, pois o comprimento recebido pode ser usado para determinar se a conversão foi bem-sucedida. Essa rotina não modifica a cadeia de caracteres de origem. Ele retornará uma cadeia de caracteres UTF-8 terminada em nulo se o UnicodeStringSource especificado incluir um terminador NULL e se o UTF8StringMaxByteCount especificado não causar truncamento.
Se a saída for truncada e um caractere de entrada inválido for encontrado, a função retornará STATUS_BUFFER_TOO_SMALL erro.
Se UTF8StringDestination estiver definido como NULL , a função retornará o número necessário de bytes para hospedar a cadeia de caracteres traduzida sem nenhum truncamento em UTF8StringActualByteCount.
Os chamadores de RtlUnicodeToUTF8N devem estar em execução no IRQL < DISPATCH_LEVEL.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte |
Windows 7 [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte |
Windows Server 2008 R2 [somente aplicativos da área de trabalho] |
| Cabeçalho |
|
| DLL |
|
Confira também