Função WideCharToMultiByte (stringapiset.h)
Mapeia uma cadeia de caracteres UTF-16 (caractere largo) para uma nova cadeia de caracteres. A nova cadeia de caracteres não é necessariamente de um conjunto de caracteres multibyte.
Os dados convertidos de codificações UTF-16 para não Unicode estão sujeitos à perda de dados, pois uma página de código pode não ser capaz de representar todos os caracteres usados nos dados Unicode específicos. Para obter mais informações, consulte Considerações de segurança: recursos internacionais.
Sintaxe
int WideCharToMultiByte(
[in] UINT CodePage,
[in] DWORD dwFlags,
[in] _In_NLS_string_(cchWideChar)LPCWCH lpWideCharStr,
[in] int cchWideChar,
[out, optional] LPSTR lpMultiByteStr,
[in] int cbMultiByte,
[in, optional] LPCCH lpDefaultChar,
[out, optional] LPBOOL lpUsedDefaultChar
);
Parâmetros
[in] CodePage
Página de código a ser usada na execução da conversão. Esse parâmetro pode ser definido como o valor de qualquer página de código instalada ou disponível no sistema operacional. Para obter uma lista de páginas de código, consulte Identificadores de página de código. Seu aplicativo também pode especificar um dos valores mostrados na tabela a seguir.
[in] dwFlags
Sinalizadores que indicam o tipo de conversão. O aplicativo pode especificar uma combinação dos valores a seguir. A função é executada mais rapidamente quando nenhum desses sinalizadores é definido. O aplicativo deve especificar WC_NO_BEST_FIT_CHARS e WC_COMPOSITECHECK com o valor específico WC_DEFAULTCHAR para recuperar todos os resultados de conversão possíveis. Se os três valores não forem fornecidos, alguns resultados estarão ausentes.
| Valor | Significado | ||||||
|---|---|---|---|---|---|---|---|
|
Converta caracteres compostos, que consistem em um caractere base e um caractere sem espaçamento, cada um com valores de caracteres diferentes. Traduza esses caracteres em caracteres pré-colocados, que têm um único valor de caractere para uma combinação de caracteres de não espaçamento de base. Por exemplo, no caractere è, o e é o caractere base e a marca de acento grave é o caractere sem espaçamento. Nota O Windows normalmente representa cadeias de caracteres Unicode com dados pré-compilados, tornando desnecessário o uso do sinalizador WC_COMPOSITECHECK.
Seu aplicativo pode combinar WC_COMPOSITECHECK com qualquer um dos sinalizadores a seguir, sendo o padrão WC_SEPCHARS. Esses sinalizadores determinam o comportamento da função quando nenhum mapeamento pré-compilado para uma combinação de caracteres não espaçamento de base em uma cadeia de caracteres Unicode está disponível. Se nenhum desses sinalizadores for fornecido, a função se comportará como se o sinalizador WC_SEPCHARS estivesse definido. Para obter mais informações, consulte WC_COMPOSITECHECK e sinalizadores relacionados na seção Comentários .
|
||||||
|
Windows Vista e posterior: Falha (retornando 0 e definindo o código de último erro como ERROR_NO_UNICODE_TRANSLATION) se um caractere de entrada inválido for encontrado. Você pode recuperar o código do último erro com uma chamada para GetLastError. Se esse sinalizador não estiver definido, a função substituirá sequências ilegais por U+FFFD (codificado conforme apropriado para a página de código especificada) e terá êxito retornando o comprimento da cadeia de caracteres convertida. Observe que esse sinalizador só se aplica quando CodePage é especificado como CP_UTF8 ou 54936. Ele não pode ser usado com outros valores de página de código. | ||||||
|
Traduza todos os caracteres Unicode que não são convertidos diretamente em equivalentes multibyte para o caractere padrão especificado por lpDefaultChar. Em outras palavras, se a conversão de Unicode para multibyte e voltar para Unicode novamente não produzir o mesmo caractere Unicode, a função usará o caractere padrão. Esse sinalizador pode ser usado por si só ou em combinação com os outros sinalizadores definidos.
Para cadeias de caracteres que exigem validação, como nomes de arquivo, recurso e usuário, o aplicativo sempre deve usar o sinalizador WC_NO_BEST_FIT_CHARS. Esse sinalizador impede que a função mapeia caracteres para caracteres que parecem semelhantes, mas têm semântica muito diferente. Em alguns casos, a alteração semântica pode ser extrema. Por exemplo, o símbolo de "∞" (infinito) mapeia para 8 (oito) em algumas páginas de código. |
Para as páginas de código listadas abaixo, dwFlags deve ser 0. Caso contrário, a função falhará com ERROR_INVALID_FLAGS.
- 50220
- 50221
- 50222
- 50225
- 50227
- 50229
- 57002 a 57011
- 65000 (UTF-7)
- 42 (Símbolo)
[in] lpWideCharStr
Ponteiro para a cadeia de caracteres Unicode a ser convertida.
[in] cchWideChar
Tamanho, em caracteres, da cadeia de caracteres indicada por lpWideCharStr. Como alternativa, esse parâmetro poderá ser definido como -1 se a cadeia de caracteres for terminada em nulo. Se cchWideChar estiver definido como 0, a função falhará.
Se esse parâmetro for -1, a função processará toda a cadeia de caracteres de entrada, incluindo o caractere nulo de terminação. Portanto, a cadeia de caracteres resultante tem um caractere nulo de terminação e o comprimento retornado pela função inclui esse caractere.
Se esse parâmetro for definido como um inteiro positivo, a função processará exatamente o número especificado de caracteres. Se o tamanho fornecido não incluir um caractere nulo de terminação, a cadeia de caracteres resultante não será terminada em nulo e o comprimento retornado não incluirá esse caractere.
[out, optional] lpMultiByteStr
Ponteiro para um buffer que recebe a cadeia de caracteres convertida.
[in] cbMultiByte
Tamanho, em bytes, do buffer indicado por lpMultiByteStr. Se esse valor for 0, a função retornará o tamanho do buffer necessário, em bytes, incluindo qualquer caractere nulo de terminação e não usará o buffer lpMultiByteStr .
[in, optional] lpDefaultChar
Ponteiro para o caractere a ser usado se um caractere não puder ser representado na página de código especificada. O aplicativo define esse parâmetro como NULL se a função usar um valor padrão do sistema. Para obter o caractere padrão do sistema, o aplicativo pode chamar a função GetCPInfo ou GetCPInfoEx .
Para as configurações de CP_UTF7 e CP_UTF8 para CodePage, esse parâmetro deve ser definido como NULL. Caso contrário, a função falhará com ERROR_INVALID_PARAMETER.
[out, optional] lpUsedDefaultChar
Ponteiro para um sinalizador que indica se a função usou um caractere padrão na conversão. O sinalizador será definido como TRUE se um ou mais caracteres na cadeia de caracteres de origem não puderem ser representados na página de código especificada. Caso contrário, o sinalizador será definido como FALSE. Esse parâmetro pode ser definido como NULL.
Para as configurações de CP_UTF7 e CP_UTF8 para CodePage, esse parâmetro deve ser definido como NULL. Caso contrário, a função falhará com ERROR_INVALID_PARAMETER.
Retornar valor
Se tiver êxito, retornará o número de bytes gravados no buffer apontado por lpMultiByteStr. Se a função for bem-sucedida e cbMultiByte for 0, o valor retornado será o tamanho necessário, em bytes, para o buffer indicado por lpMultiByteStr. Consulte também dwFlags para obter informações sobre como o sinalizador WC_ERR_INVALID_CHARS afeta o valor retornado quando sequências inválidas são inseridas.
A função retornará 0 se não for bem-sucedida. Para obter informações de erro estendidas, o aplicativo pode chamar GetLastError, que pode retornar um dos seguintes códigos de erro:
- ERROR_INSUFFICIENT_BUFFER. Um tamanho de buffer fornecido não era grande o suficiente ou foi definido incorretamente como NULL.
- ERROR_INVALID_FLAGS. Os valores fornecidos para sinalizadores não eram válidos.
- ERROR_INVALID_PARAMETER. Qualquer um dos valores de parâmetro era inválido.
- ERROR_NO_UNICODE_TRANSLATION. Unicode inválido foi encontrado em uma cadeia de caracteres.
Comentários
Os ponteiros lpMultiByteStr e lpWideCharStr não devem ser os mesmos. Se forem iguais, a função falhará e GetLastError retornará ERROR_INVALID_PARAMETER.
WideCharToMultiByte não encerrará nulo uma cadeia de caracteres de saída se o comprimento da cadeia de caracteres de entrada for especificado explicitamente sem um caractere nulo de terminação. Para encerrar nulo uma cadeia de caracteres de saída para essa função, o aplicativo deve passar -1 ou contar explicitamente o caractere nulo de terminação para a cadeia de caracteres de entrada.
Se cbMultiByte for menor que cchWideChar, essa função gravará o número de caracteres especificado por cbMultiByte no buffer indicado por lpMultiByteStr. No entanto, se CodePage estiver definido como CP_SYMBOL e cbMultiByte for menor que cchWideChar, a função não gravará caracteres em lpMultiByteStr.
A função WideCharToMultiByte opera com mais eficiência quando lpDefaultChar e lpUsedDefaultChar são definidos como NULL. A tabela a seguir mostra o comportamento da função para as quatro combinações possíveis desses parâmetros.
| lpDefaultChar | Lpuseddefaultchar | Result |
|---|---|---|
| NULL | NULL | Nenhuma verificação padrão. Essas configurações de parâmetro são as mais eficientes para uso com essa função. |
| Caractere não nulo | NULL | Usa o caractere padrão especificado, mas não define lpUsedDefaultChar. |
| NULL | Caractere não nulo | Usa o caractere padrão do sistema e define lpUsedDefaultChar , se necessário. |
| Caractere não nulo | Caractere não nulo | Usa o caractere padrão especificado e define lpUsedDefaultChar , se necessário. |
A partir do Windows Vista, essa função está totalmente em conformidade com a especificação Unicode 4.1 para UTF-8 e UTF-16. A função usada em sistemas operacionais anteriores codifica ou decodifica metades substitutas solitárias ou pares alternativos incompatíveis. O código escrito em versões anteriores do Windows que dependem desse comportamento para codificar dados binários aleatórios não textuais pode ter problemas. No entanto, o código que usa essa função para produzir cadeias de caracteres UTF-8 válidas se comportará da mesma maneira que em sistemas operacionais Windows anteriores.
Começando com Windows 8: WideCharToMultiByte é declarado em Stringapiset.h. Antes de Windows 8, ele foi declarado em Winnls.h.
WC_COMPOSITECHECK e sinalizadores relacionados
Conforme discutido em Usando a normalização Unicode para representar cadeias de caracteres, Unicode permite várias representações da mesma cadeia de caracteres (interpretada linguisticamente). Por exemplo, Capital A com dieresis (umlaut) pode ser representado como um único ponto de código Unicode "Ä" (U+00C4) ou decomposto como a combinação de Capital A e o caractere de dieresis combinado ("A" + " ̈", que é U+0041 U+0308). No entanto, a maioria das páginas de código fornece apenas caracteres compostos.O sinalizador WC_COMPOSITECHECK faz com que a função WideCharToMultiByte teste caracteres Unicode decompostos e tenta compô-los antes de convertê-los na página de código solicitada. Esse sinalizador só está disponível para conversão em SBCS (byte único) ou páginas de código DBCS (byte duplo) (páginas < de código 50000, excluindo a página de código 42). Se o aplicativo precisar converter dados Unicode decompostos em páginas de código de byte único ou byte duplo, esse sinalizador poderá ser útil. No entanto, nem todos os caracteres podem ser convertidos dessa maneira e é mais confiável salvar e armazenar dados como Unicode.
Quando um aplicativo está usando WC_COMPOSITECHECK, algumas combinações de caracteres podem permanecer incompletas ou podem ter caracteres adicionais sem espaçamento restantes. Por exemplo, A + ̈ + ̈ combina com Ä + ̈. Usar o sinalizador WC_DISCARDNS faz com que a função descarte caracteres adicionais sem espaçamento. Usar o sinalizador WC_DEFAULTCHAR faz com que a função use o caractere de substituição padrão (normalmente "?") em vez disso. O uso do sinalizador WC_SEPCHARS faz com que a função tente converter cada caractere de não espaçamento adicional na página de código de destino. Normalmente, esse sinalizador também causa o uso do caractere de substituição ("?"). No entanto, para a página de código 1258 (vietnamita) e 20269, existem caracteres sem espaçamento e podem ser usados. As conversões para essas páginas de código não são perfeitas. Algumas combinações não são convertidas corretamente na página de código 1258 e WC_COMPOSITECHECK corrompe dados na página de código 20269. Conforme mencionado anteriormente, é mais confiável criar seu aplicativo para salvar e armazenar dados como Unicode.
Exemplos
ISDSC_STATUS DiscpUnicodeToAnsiSize(
IN __in PWCHAR UnicodeString,
OUT ULONG *AnsiSizeInBytes
)
/*++
Routine Description:
This routine will return the length needed to represent the unicode
string as ANSI
Arguments:
UnicodeString is the unicode string whose ansi length is returned
*AnsiSizeInBytes is number of bytes needed to represent unicode
string as ANSI
Return Value:
ERROR_SUCCESS or error code
--*/
{
_try
{
*AnsiSizeInBytes = WideCharToMultiByte(CP_ACP,
0,
UnicodeString,
-1,
NULL,
0, NULL, NULL);
} _except(EXCEPTION_EXECUTE_HANDLER) {
return(ERROR_NOACCESS);
}
return((*AnsiSizeInBytes == 0) ? GetLastError() : ERROR_SUCCESS);
}
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | stringapiset.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |
Confira também
Funções unicode e conjunto de caracteres