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.

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.

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.

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

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

Confira também

MultiByteToWideChar

Funções unicode e conjunto de caracteres

Conjuntos de caracteres e Unicode

APIs Vertdll disponíveis em enclaves de VBS