Función MultiByteToWideChar (stringapiset.h)
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.
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.
[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. |
- MB_PRECOMPOSED
- MB_USEGLYPHCHARS
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
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
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