Função MultiByteToWideChar (stringapiset.h)

Artigo
02/05/2024

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.

Cuidado Usar a função MultiByteToWideChar incorretamente pode comprometer a segurança do aplicativo. Chamar essa função pode facilmente causar uma sobrecarga de buffer porque o tamanho do buffer de entrada indicado por lpMultiByteStr é igual ao número de bytes na cadeia de caracteres, enquanto o tamanho do buffer de saída indicado por lpWideCharStr é igual ao número de caracteres. Para evitar uma sobrecarga de buffer, seu aplicativo deve especificar um tamanho de buffer apropriado para o tipo de dados que o buffer recebe. Para obter mais informações, consulte Considerações sobre segurança: recursos internacionais.

Observação 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 o 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 do Unicode. Se o uso do Unicode não for possível, 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 marcação, mas arquivos de texto não.

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.

Valor	Significado
CP_ACP	A página de código ANSI do Windows padrão do sistema. Observação 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. Observação 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. Observação Esse valor é usado principalmente no 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. Observação 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	Página de código de símbolo (42).
CP_THREAD_ACP	A página de código ANSI do Windows para o thread atual. Observação 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.
CP_UTF8	UTF-8.

[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	Falhará 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.

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

Falhará 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

Inadimplência; não use com MB_COMPOSITE. Sempre use caracteres pré-colocados, ou seja, caracteres com um único valor de caractere para uma combinação de caracteres base ou sem espaçamento. Por exemplo, no caractere è, o e é o caractere base e a marca de acento grave é o caractere sem espaçamento. Se um único ponto de código Unicode for definido para um caractere, o aplicativo deverá usá-lo em vez de um caractere base separado e um caractere sem espaçamento. Por exemplo, Ä é representado pelo único ponto de código Unicode LATIN CAPITAL LETTER A WITH DIAERESIS (U+00C4).

MB_USEGLYPHCHARS

Use caracteres de glifo em vez de caracteres de controle.

Para as páginas de código listadas abaixo, dwFlags deve ser definido como 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 UTF-8 ou página de código 54936 (GB18030, começando com o Windows Vista), dwFlags devem ser definidos 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 pode 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 encerramento. Portanto, a cadeia de caracteres Unicode resultante tem um caractere nulo de encerramento 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á encerrada 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 , a função retornará o tamanho do buffer necessário, em caracteres, incluindo qualquer caractere nulo de encerramento e não usará o buffer de lpWideCharStr .

Valor de retorno

Retorna o número de caracteres gravados no buffer indicado por lpWideCharStr se bem-sucedido. 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 inválidas.

A função retornará 0 se não tiver êxito. 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.

Observações

O comportamento padrão dessa função é traduzir para uma forma pré-configurada da cadeia de caracteres de entrada. Se um formulário pré-composto 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 no aviso 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 0 para 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 se traduz 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 liderança, 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 o substituto metades 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 sem texto 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 curta de caracteres UTF-8, MultiByteToWideChar exclui esses caracteres.

Começando com o Windows 8: MultiByteToWideChar é declarado em Stringapiset.h. Antes do 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 de Exemplos Universais do Windows no GitHub.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows 2000 Server [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	stringapiset.h (inclua Windows.h)
biblioteca	Kernel32.lib
de DLL	Kernel32.dll

Consulte também

unicode e funções de conjunto de caracteres

unicode e conjuntos de caracteres

WideCharToMultiByte

APIs Vertdll disponíveis em enclaves de VBS

Compartilhar via