Função MultiByteToWideChar (stringapiset.h)
Mapeia uma cadeia de caracteres para uma cadeia de caracteres UTF-16 (caractere largo). A cadeia de caracteres não é necessariamente de um conjunto de caracteres multibyte.
Sintaxe
int MultiByteToWideChar(
[in] UINT CodePage,
[in] DWORD dwFlags,
[in] _In_NLS_string_(cbMultiByte)LPCCH lpMultiByteStr,
[in] int cbMultiByte,
[out, optional] LPWSTR lpWideCharStr,
[in] int cchWideChar
);
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, com MB_PRECOMPOSED sendo o padrão. MB_PRECOMPOSED e MB_COMPOSITE são mutuamente exclusivos. MB_USEGLYPHCHARS e MB_ERR_INVALID_CHARS podem ser definidos independentemente do estado dos outros sinalizadores.
| Valor | Significado |
|---|---|
| MB_COMPOSITE | Sempre use caracteres decompostos, ou seja, caracteres em que um caractere base e um ou mais caracteres sem espaçamento têm valores distintos de ponto de código. Por exemplo, Ä é representado por A + ̈: LATIN CAPITAL LETTER A (U+0041) + COMBINING DIAERESIS (U+0308). Observe que esse sinalizador não pode ser usado com MB_PRECOMPOSED. |
| MB_ERR_INVALID_CHARS | Falha se um caractere de entrada inválido for encontrado. A partir do Windows Vista, a função não descartará pontos de código ilegais se o aplicativo não definir esse sinalizador, mas substituirá sequências ilegais por U+FFFD (codificado conforme apropriado para a página de código especificada). Windows 2000 com SP4 e posterior, Windows XP: Se esse sinalizador não estiver definido, a função removerá silenciosamente pontos de código ilegais. Uma chamada para GetLastError retorna ERROR_NO_UNICODE_TRANSLATION. |
- MB_PRECOMPOSED
- MB_USEGLYPHCHARS
Para as páginas de código listadas abaixo, dwFlags deve ser definido 0como . 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)
Observação
Para UTF-8 ou página de código 54936 (GB18030, começando com o Windows Vista), dwFlags deve ser definido como 0 ou MB_ERR_INVALID_CHARS. Caso contrário, a função falhará com ERROR_INVALID_FLAGS.
[in] lpMultiByteStr
Ponteiro para a cadeia de caracteres a ser convertida.
[in] cbMultiByte
Tamanho, em bytes, da cadeia de caracteres indicada pelo parâmetro lpMultiByteStr . Como alternativa, esse parâmetro poderá ser definido como -1 se a cadeia de caracteres for terminada em nulo. Observe que, se cbMultiByte for 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 Unicode 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 bytes. Se o tamanho fornecido não incluir um caractere nulo de terminação, a cadeia de caracteres Unicode resultante não será terminada em nulo e o comprimento retornado não incluirá esse caractere.
[out, optional] lpWideCharStr
Ponteiro para um buffer que recebe a cadeia de caracteres convertida.
[in] cchWideChar
Tamanho, em caracteres, do buffer indicado por lpWideCharStr. Se esse valor for 0, a função retornará o tamanho do buffer necessário, em caracteres, incluindo qualquer caractere nulo de terminação e não usará o buffer lpWideCharStr .
Retornar valor
Retorna o número de caracteres gravados no buffer indicado por lpWideCharStr se tiver êxito. Se a função for bem-sucedida e cchWideChar for 0, o valor retornado será o tamanho necessário, em caracteres, para o buffer indicado por lpWideCharStr. Consulte também dwFlags para obter informações sobre como o sinalizador MB_ERR_INVALID_CHARS afeta o valor retornado quando sequências inválidas são entradas.
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
O comportamento padrão dessa função é traduzir para uma forma pré-configurada da cadeia de caracteres de entrada. Se um formulário pré-colocado não existir, a função tentará traduzir para um formulário composto.
O uso do sinalizador MB_PRECOMPOSED tem muito pouco efeito na maioria das páginas de código porque a maioria dos dados de entrada já é composta. Considere chamar NormalizeString depois de converter com MultiByteToWideChar. NormalizeString fornece dados mais precisos, padrão e consistentes e também pode ser mais rápido. Observe que, para a enumeração NORM_FORM que está sendo passada para NormalizeString, NormalizationC corresponde a MB_PRECOMPOSED e NormalizationD corresponde a MB_COMPOSITE.
Conforme mencionado na cautela acima, o buffer de saída poderá ser facilmente invadido se essa função não for chamada pela primeira vez com cchWideChar definido como para 0 obter o tamanho necessário. Se o sinalizador MB_COMPOSITE for usado, a saída poderá ter três ou mais caracteres para cada caractere de entrada.
Os ponteiros lpMultiByteStr e lpWideCharStr não devem ser os mesmos. Se forem iguais, a função falhará e GetLastError retornará o valor ERROR_INVALID_PARAMETER.
MultiByteToWideChar 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.
A função falhará se MB_ERR_INVALID_CHARS estiver definido e um caractere inválido for encontrado na cadeia de caracteres de origem. Um caractere inválido é um dos seguintes:
- Um caractere que não é o caractere padrão na cadeia de caracteres de origem, mas é convertido para o caractere padrão quando MB_ERR_INVALID_CHARS não está definido.
- Para cadeias de caracteres DBCS, um caractere que tem um byte de chumbo, mas nenhum byte de trilha válido.
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 em cadeias de caracteres UTF-8 válidas se comportará da mesma maneira que em sistemas operacionais Windows anteriores.
Windows XP: Para evitar o problema de segurança das versões de forma não mais curtas de caracteres UTF-8, MultiByteToWideChar exclui esses caracteres.
Começando com Windows 8:MultiByteToWideChar é declarado em Stringapiset.h. Antes de Windows 8, ele foi declarado em Winnls.h.
Exemplo de código
catch (std::exception e)
{
// Save in-memory logging buffer to a log file on error.
::std::wstring wideWhat;
if (e.what() != nullptr)
{
int convertResult = MultiByteToWideChar(CP_UTF8, 0, e.what(), (int)strlen(e.what()), NULL, 0);
if (convertResult <= 0)
{
wideWhat = L"Exception occurred: Failure to convert its message text using MultiByteToWideChar: convertResult=";
wideWhat += convertResult.ToString()->Data();
wideWhat += L" GetLastError()=";
wideWhat += GetLastError().ToString()->Data();
}
else
{
wideWhat.resize(convertResult + 10);
convertResult = MultiByteToWideChar(CP_UTF8, 0, e.what(), (int)strlen(e.what()), &wideWhat[0], (int)wideWhat.size());
if (convertResult <= 0)
{
wideWhat = L"Exception occurred: Failure to convert its message text using MultiByteToWideChar: convertResult=";
wideWhat += convertResult.ToString()->Data();
wideWhat += L" GetLastError()=";
wideWhat += GetLastError().ToString()->Data();
}
else
{
wideWhat.insert(0, L"Exception occurred: ");
}
}
}
else
{
wideWhat = L"Exception occurred: Unknown.";
}
Platform::String^ errorMessage = ref new Platform::String(wideWhat.c_str());
// The session added the channel at level Warning. Log the message at
// level Error which is above (more critical than) Warning, which
// means it will actually get logged.
_channel->LogMessage(errorMessage, LoggingLevel::Error);
SaveLogInMemoryToFileAsync().then([=](StorageFile^ logFile) {
_logFileGeneratedCount++;
StatusChanged(this, ref new LoggingScenarioEventArgs(LoggingScenarioEventType::LogFileGenerated, logFile->Path->Data()));
}).wait();
}
Exemplo de Exemplos Universais do Windows no GitHub.
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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de