Función MultiByteToWideChar (stringapiset.h)

Artículo
07/16/2024

Asigna una cadena de caracteres a una cadena UTF-16 (carácter ancho). La cadena de caracteres no es necesariamente de un juego de caracteres multibyte.

precaución Usar la función multibyteToWideChar de incorrectamente puede poner en peligro la seguridad de la aplicación. Llamar a esta función puede provocar fácilmente una saturación del búfer porque el tamaño del búfer de entrada indicado por lpMultiByteStr es igual al número de bytes de la cadena, mientras que el tamaño del búfer de salida indicado por lpWideCharStr es igual al número de caracteres. Para evitar una saturación del búfer, la aplicación debe especificar un tamaño de búfer adecuado para el tipo de datos que recibe el búfer. Para obtener más información, vea Consideraciones de seguridad: Características internacionales.

Nota Las páginas de códigos ANSI pueden ser diferentes en equipos diferentes o se pueden cambiar para un solo equipo, lo que provoca daños en los datos. Para los resultados más coherentes, las aplicaciones deben usar Unicode, como UTF-8 o UTF-16, en lugar de una página de códigos específica, a menos que los estándares heredados o los formatos de datos impidan el uso de Unicode. Si no es posible usar Unicode, las aplicaciones deben etiquetar el flujo de datos con el nombre de codificación adecuado cuando los protocolos lo permitan. Los archivos HTML y XML permiten el etiquetado, pero no los archivos de texto.

Sintaxis

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ódigos que se va a usar para realizar la conversión. Este parámetro se puede establecer en el valor de cualquier página de códigos instalada o disponible en el sistema operativo. Para obtener una lista de páginas de códigos, consulte identificadores de página de códigos. La aplicación también puede especificar uno de los valores que se muestran en la tabla siguiente.

Valor	Significado
CP_ACP	Página de códigos ANSI de Windows predeterminada del sistema. Nota Este valor puede ser diferente en equipos diferentes, incluso en la misma red. Se puede cambiar en el mismo equipo, lo que hace que los datos almacenados se vuelvan dañados irrecuperablemente. Este valor solo está pensado para uso temporal y el almacenamiento permanente debe usar UTF-16 o UTF-8 si es posible.
CP_MACCP	Página de códigos de Macintosh del sistema actual. Nota Este valor puede ser diferente en equipos diferentes, incluso en la misma red. Se puede cambiar en el mismo equipo, lo que hace que los datos almacenados se vuelvan dañados irrecuperablemente. Este valor solo está pensado para uso temporal y el almacenamiento permanente debe usar UTF-16 o UTF-8 si es posible. Nota Este valor se usa principalmente en código heredado y no suele ser necesario, ya que los equipos Macintosh modernos usan Unicode para la codificación.
CP_OEMCP	Página de códigos del OEM del sistema actual. Nota Este valor puede ser diferente en equipos diferentes, incluso en la misma red. Se puede cambiar en el mismo equipo, lo que hace que los datos almacenados se vuelvan dañados irrecuperablemente. Este valor solo está pensado para uso temporal y el almacenamiento permanente debe usar UTF-16 o UTF-8 si es posible.
CP_SYMBOL	Página de códigos de símbolos (42).
CP_THREAD_ACP	Página de códigos ANSI de Windows para el subproceso actual. Nota Este valor puede ser diferente en equipos diferentes, incluso en la misma red. Se puede cambiar en el mismo equipo, lo que hace que los datos almacenados se vuelvan dañados irrecuperablemente. Este valor solo está pensado para uso temporal y el almacenamiento permanente debe usar UTF-16 o UTF-8 si es posible.
CP_UTF7	UTF-7. Use este valor solo cuando sea forzado por un mecanismo de transporte de 7 bits. Se prefiere el uso de UTF-8.
CP_UTF8	UTF-8.

[in] dwFlags

Marcas que indican el tipo de conversión. La aplicación puede especificar una combinación de los siguientes valores, con MB_PRECOMPOSED siendo el valor predeterminado. MB_PRECOMPOSED y MB_COMPOSITE son mutuamente excluyentes. MB_USEGLYPHCHARS y MB_ERR_INVALID_CHARS se pueden establecer independientemente del estado de las otras marcas.

Valor	Significado
MB_COMPOSITE	Use siempre caracteres descomponidos, es decir, caracteres en los que un carácter base y uno o varios caracteres sin espaciado cada uno tienen valores de punto de código distintos. Por ejemplo, Ä se representa mediante A + ́: LETRA MAYÚSCULA LATINA A (U+0041) + COMBINACIÓN DE DIAERESIS (U+0308). Tenga en cuenta que esta marca no se puede usar con MB_PRECOMPOSED.
MB_ERR_INVALID_CHARS	Error si se encuentra un carácter de entrada no válido. A partir de Windows Vista, la función no quita puntos de código no válidos si la aplicación no establece esta marca, sino que reemplaza secuencias no válidas por U+FFFD (codificada según corresponda para la página de códigos especificada). Windows 2000 con SP4 y versiones posteriores, Windows XP: Si no se establece esta marca, la función quita silenciosamente puntos de código no válidos. Una llamada a GetLastError devuelve ERROR_NO_UNICODE_TRANSLATION.

Valor

Significado

MB_COMPOSITE

Use siempre caracteres descomponidos, es decir, caracteres en los que un carácter base y uno o varios caracteres sin espaciado cada uno tienen valores de punto de código distintos. Por ejemplo, Ä se representa mediante A + ́: LETRA MAYÚSCULA LATINA A (U+0041) + COMBINACIÓN DE DIAERESIS (U+0308). Tenga en cuenta que esta marca no se puede usar con MB_PRECOMPOSED.

MB_ERR_INVALID_CHARS

Error si se encuentra un carácter de entrada no válido.

A partir de Windows Vista, la función no quita puntos de código no válidos si la aplicación no establece esta marca, sino que reemplaza secuencias no válidas por U+FFFD (codificada según corresponda para la página de códigos especificada).

Windows 2000 con SP4 y versiones posteriores, Windows XP: Si no se establece esta marca, la función quita silenciosamente puntos de código no válidos. Una llamada a GetLastError devuelve ERROR_NO_UNICODE_TRANSLATION.

MB_PRECOMPOSED

Predeterminado; no use con MB_COMPOSITE. Use siempre caracteres precomponidos, es decir, caracteres que tengan un único valor de carácter para una combinación de caracteres base o no espaciado. Por ejemplo, en el carácter è, el e es el carácter base y la grave de énfasis es el carácter sin espaciado. Si se define un único punto de código Unicode para un carácter, la aplicación debe usarla en lugar de un carácter base independiente y un carácter no espaciado. Por ejemplo, Ä se representa mediante el único punto de código Unicode LATIN CAPITAL LETTER A WITH DIAERESIS (U+00C4).

MB_USEGLYPHCHARS

Use caracteres de glifo en lugar de caracteres de control.

Para las páginas de códigos que se enumeran a continuación, dwFlags debe establecerse en 0. De lo contrario, se produce un error en la función con ERROR_INVALID_FLAGS.

50220
50221
50222
50225
50227
50229
De 57002 a 57011
65000 (UTF-7)
42 (símbolo)

Nota

Para UTF-8 o página de códigos 54936 (GB18030, a partir de Windows Vista), dwFlags debe establecerse en 0 o MB_ERR_INVALID_CHARS. De lo contrario, se produce un error en la función con ERROR_INVALID_FLAGS.

[in] lpMultiByteStr

Puntero a la cadena de caracteres que se va a convertir.

[in] cbMultiByte

Tamaño, en bytes, de la cadena indicada por el parámetro lpMultiByteStr. Como alternativa, este parámetro se puede establecer en -1 si la cadena está terminada en null. Tenga en cuenta que, si cbMultiByte es 0, se produce un error en la función.

Si este parámetro es -1, la función procesa toda la cadena de entrada, incluido el carácter NULO de terminación. Por lo tanto, la cadena Unicode resultante tiene un carácter NULO de terminación y la longitud devuelta por la función incluye este carácter.

Si este parámetro se establece en un entero positivo, la función procesa exactamente el número especificado de bytes. Si el tamaño proporcionado no incluye un carácter NULO de terminación, la cadena Unicode resultante no termina en null y la longitud devuelta no incluye este carácter.

[out, optional] lpWideCharStr

Puntero a un búfer que recibe la cadena convertida.

[in] cchWideChar

Tamaño, en caracteres, del búfer indicado por lpWideCharStr. Si este valor es , la función devuelve el tamaño de búfer necesario, en caracteres, incluido cualquier carácter NULO de terminación, y no usa el búfer de lpWideCharStr de .

Valor devuelto

Devuelve el número de caracteres escritos en el búfer indicado por lpWideCharStr si se ejecuta correctamente. Si la función se realiza correctamente y cchWideChar es 0, el valor devuelto es el tamaño requerido, en caracteres, para el búfer indicado por lpWideCharStr. Consulte también dwFlags para obtener información sobre cómo afecta la marca de MB_ERR_INVALID_CHARS al valor devuelto cuando se introducen secuencias no válidas.

La función devuelve 0 si no se realiza correctamente. Para obtener información de error extendida, la aplicación puede llamar a GetLastError, que puede devolver uno de los siguientes códigos de error:

ERROR_INSUFFICIENT_BUFFER: un tamaño de búfer proporcionado no era lo suficientemente grande o se estableció incorrectamente en NULL.
ERROR_INVALID_FLAGS: los valores proporcionados para las marcas no eran válidos.
ERROR_INVALID_PARAMETER: cualquiera de los valores de parámetro no era válido.
ERROR_NO_UNICODE_TRANSLATION: Se encontró unicode no válido en una cadena.

Observaciones

El comportamiento predeterminado de esta función es traducir a una forma precomponida de la cadena de caracteres de entrada. Si no existe un formulario precomponido, la función intenta traducir a un formulario compuesto.

El uso de la marca MB_PRECOMPOSED tiene muy poco efecto en la mayoría de las páginas de códigos porque la mayoría de los datos de entrada ya están compuestos. Considere la posibilidad de llamar a NormalizeString después de convertir con MultiByteToWideChar. normalizeString proporciona datos más precisos, estándar y coherentes, y también puede ser más rápido. Tenga en cuenta que para la enumeración NORM_FORM que se pasa a NormalizeString, NormalizationC corresponde a MB_PRECOMPOSED y NormalizationD corresponde a MB_COMPOSITE.

Como se mencionó anteriormente, el búfer de salida puede saturarse fácilmente si no se llama a esta función por primera vez con cchWideChar establecido en 0 para obtener el tamaño necesario. Si se usa la marca MB_COMPOSITE, la salida puede tener tres o más caracteres para cada carácter de entrada.

Los lpMultiByteStr de y lpWideCharStr no deben ser los mismos. Si son iguales, se produce un error en la función y GetLastError devuelve el valor ERROR_INVALID_PARAMETER.

MultiByteToWideChar no finaliza una cadena de salida si la longitud de la cadena de entrada se especifica explícitamente sin un carácter NULO de terminación. Para finalizar un valor NULL en una cadena de salida para esta función, la aplicación debe pasar -1 o contar explícitamente el carácter nulo de terminación de la cadena de entrada.

Se produce un error en la función si se establece MB_ERR_INVALID_CHARS y se encuentra un carácter no válido en la cadena de origen. Un carácter no válido es uno de los siguientes:

Carácter que no es el carácter predeterminado de la cadena de origen, pero se traduce al carácter predeterminado cuando no se establece MB_ERR_INVALID_CHARS.
En el caso de las cadenas DBCS, un carácter que tiene un byte inicial, pero ningún byte final válido.

A partir de Windows Vista, esta función se ajusta completamente a la especificación Unicode 4.1 para UTF-8 y UTF-16. La función usada en sistemas operativos anteriores codifica o descodifica suplentes mitades o pares suplentes no coincidentes. El código escrito en versiones anteriores de Windows que dependen de este comportamiento para codificar datos binarios no de texto aleatorios podría tener problemas. Sin embargo, el código que usa esta función en cadenas UTF-8 válidas se comportará del mismo modo que en sistemas operativos Windows anteriores.

Windows XP: Para evitar el problema de seguridad de las versiones sin formato más corto de caracteres UTF-8, MultiByteToWideChar elimina estos caracteres.

a partir de Windows 8: MultiByteToWideChar se declara en Stringapiset.h. Antes de Windows 8, se declaró en Winnls.h.

Ejemplo 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();
}

Ejemplo de ejemplos universales de Windows en GitHub.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional [aplicaciones de escritorio \| Aplicaciones para UWP]
servidor mínimo admitido	Windows 2000 Server [aplicaciones de escritorio \| Aplicaciones para UWP]
de la plataforma de destino de	Windows
encabezado de	stringapiset.h (incluya Windows.h)
biblioteca de	Kernel32.lib
DLL de	Kernel32.dll

Consulte también

funciones Unicode y Juego de caracteres

conjuntos de caracteres y Unicode

WideCharToMultiByte

API de Vertdll disponibles en enclaves de VBS

Compartir a través de