Función MultiByteToWideChar (stringapiset.h)
Asigna una cadena de caracteres a una cadena UTF-16 (caracteres anchos). 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 que esté instalada o disponible en el sistema operativo. Para obtener una lista de páginas de códigos, vea 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 valores siguientes, 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 espaciar 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 | Se produce un 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 ilegales 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 0en . De lo contrario, se produce un error en la función ERROR_INVALID_FLAGS.
- 50220
- 50221
- 50222
- 50225
- 50227
- 50229
- 57002 a 57011
- 65000 (UTF-7)
- 42 (símbolo)
Nota
Para UTF-8 o la página de códigos 54936 (GB18030, a partir de Windows Vista), dwFlags debe establecerse 0 en o en MB_ERR_INVALID_CHARS. De lo contrario, se produce un error en la función 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 termina 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 0, 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 lpWideCharStr .
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 ejecuta correctamente y cchWideChar es 0, el valor devuelto es el tamaño necesario, 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 escriben 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ó
NULLincorrectamente en . - 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.
Comentarios
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ó con precaución anterior, el búfer de salida se puede saturar fácilmente si no se llama a esta función por primera vez con cchWideChar establecido 0 en 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 punteros lpMultiByteStr 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 null 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 para 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 no un 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 mitades suplentes de lone o pares suplentes no coincidentes. El código escrito en versiones anteriores de Windows que dependen de este comportamiento para codificar datos binarios aleatorios que no son de texto podría surgir problemas. Sin embargo, el código que usa esta función en cadenas UTF-8 válidas se comportará del mismo modo que en los sistemas operativos Windows anteriores.
Windows XP: Para evitar el problema de seguridad de las versiones de forma no corta 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 | Value |
|---|---|
| Cliente mínimo compatible | Windows 2000 Professional [aplicaciones de escritorio | Aplicaciones para UWP] |
| Servidor mínimo compatible | Windows 2000 Server [aplicaciones de escritorio | Aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | stringapiset.h (incluya Windows.h) |
| Library | Kernel32.lib |
| Archivo DLL | Kernel32.dll |
Vea también
Funciones Unicode y Juego de caracteres
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de