Compartilhar via


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.

Cuidado Usar a função WideCharToMultiByte incorretamente pode comprometer a segurança do aplicativo. Chamar essa função pode facilmente causar um estouro de buffer porque o tamanho do buffer de entrada indicado por lpWideCharStr é igual ao número de caracteres na cadeia de caracteres Unicode, enquanto o tamanho do buffer de saída indicado por lpMultiByteStr é igual ao número de bytes. Para evitar um estouro de buffer, seu aplicativo deve especificar um tamanho de buffer apropriado para o tipo de dados que o buffer recebe.

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.

 
Nota As páginas de código ANSI podem ser diferentes em computadores diferentes ou podem ser alteradas para um único computador, levando à corrupção de dados. Para obter os resultados mais consistentes, os aplicativos devem usar Unicode, como UTF-8 ou UTF-16, em vez de uma página de código específica, a menos que padrões herdados ou formatos de dados impeçam o uso de Unicode. Se não for possível usar Unicode, os aplicativos deverão marcar o fluxo de dados com o nome de codificação apropriado quando os protocolos permitirem. Arquivos HTML e XML permitem a marcação, mas os arquivos de texto não.
 

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.

Valor Significado
CP_ACP
A página de código ANSI do Windows padrão do sistema.
Nota Esse valor pode ser diferente em computadores diferentes, mesmo na mesma rede. Ele pode ser alterado no mesmo computador, levando os dados armazenados a serem corrompidos irrecuperavelmente. Esse valor destina-se apenas ao uso temporário e o armazenamento permanente deve usar UTF-16 ou UTF-8, se possível.
 
CP_MACCP
A página de código do Macintosh do sistema atual.
Nota Esse valor pode ser diferente em computadores diferentes, mesmo na mesma rede. Ele pode ser alterado no mesmo computador, levando os dados armazenados a serem corrompidos irrecuperavelmente. Esse valor destina-se apenas ao uso temporário e o armazenamento permanente deve usar UTF-16 ou UTF-8, se possível.
 
Nota Esse valor é usado principalmente em código herdado e geralmente não deve ser necessário, pois computadores Macintosh modernos usam Unicode para codificação.
 
CP_OEMCP
A página de código OEM do sistema atual.
Nota Esse valor pode ser diferente em computadores diferentes, mesmo na mesma rede. Ele pode ser alterado no mesmo computador, levando os dados armazenados a serem corrompidos irrecuperavelmente. Esse valor destina-se apenas ao uso temporário e o armazenamento permanente deve usar UTF-16 ou UTF-8, se possível.
 
CP_SYMBOL
Windows 2000: Página de código de símbolo (42).
CP_THREAD_ACP
Windows 2000: A página de código ANSI do Windows para o thread atual.
Nota Esse valor pode ser diferente em computadores diferentes, mesmo na mesma rede. Ele pode ser alterado no mesmo computador, levando os dados armazenados a serem corrompidos irrecuperavelmente. Esse valor destina-se apenas ao uso temporário e o armazenamento permanente deve usar UTF-16 ou UTF-8, se possível.
 
CP_UTF7
UTF-7. Use esse valor somente quando for forçado por um mecanismo de transporte de 7 bits. O uso de UTF-8 é preferencial. Com esse valor definido, lpDefaultChar e lpUsedDefaultChar devem ser definidos como NULL.
CP_UTF8
UTF-8. Com esse valor definido, lpDefaultChar e lpUsedDefaultChar devem ser definidos como NULL.

[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
WC_COMPOSITECHECK
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 .

WC_DEFAULTCHAR Substitua exceções pelo caractere padrão durante a conversão.
WC_DISCARDNS Descartar caracteres sem espaçamento durante a conversão.
WC_SEPCHARS Padrão. Gerar caracteres separados durante a conversão.
 
WC_ERR_INVALID_CHARS
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.
WC_NO_BEST_FIT_CHARS
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)
Nota Para a página de código 65001 (UTF-8) ou a página de código 54936 (GB18030, Windows Vista e posterior), dwFlags deve ser definido como 0 ou WC_ERR_INVALID_CHARS. Caso contrário, a função falhará com ERROR_INVALID_FLAGS.
 

[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

MultiByteToWideChar

Funções unicode e conjunto de caracteres

Conjuntos de caracteres e Unicode

APIs Vertdll disponíveis em enclaves de VBS