Función WideCharToMultiByte (stringapiset.h)
Asigna una cadena UTF-16 (caracteres anchos) a una nueva cadena de caracteres. La nueva cadena de caracteres no es necesariamente de un juego de caracteres multibyte.
Los datos convertidos de UTF-16 a codificaciones no Unicode están sujetas a pérdida de datos, ya que es posible que una página de códigos no pueda representar todos los caracteres usados en los datos Unicode específicos. Para obtener más información, vea Consideraciones de seguridad: Características internacionales.
Sintaxis
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ó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, 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 siguientes valores. La función realiza más rápidamente cuando no se establece ninguna de estas marcas. La aplicación debe especificar WC_NO_BEST_FIT_CHARS y WC_COMPOSITECHECK con el valor específico WC_DEFAULTCHAR para recuperar todos los posibles resultados de conversión. Si no se proporcionan los tres valores, faltarán algunos resultados.
| Valor | Significado | ||||||
|---|---|---|---|---|---|---|---|
|
Convierte caracteres compuestos, que constan de un carácter base y un carácter sin espaciado, cada uno con valores de carácter diferentes. Traduzca estos caracteres a caracteres precomponidos, que tienen un único valor de carácter para una combinación de caracteres sin espaciado base. Por ejemplo, en el carácter è, el e es el carácter base y la marca grave de énfasis es el carácter sin espaciado. Nota Windows normalmente representa cadenas Unicode con datos precomponidos, lo que hace que el uso de la marca WC_COMPOSITECHECK no sea necesario.
La aplicación puede combinar WC_COMPOSITECHECK con cualquiera de las siguientes marcas, con el valor predeterminado WC_SEPCHARS. Estas marcas determinan el comportamiento de la función cuando no hay ninguna asignación precomponida para una combinación de caracteres sin espaciado base en una cadena Unicode disponible. Si no se proporciona ninguna de estas marcas, la función se comporta como si se establece la marca de WC_SEPCHARS. Para obtener más información, vea WC_COMPOSITECHECK y marcas relacionadas en la sección Comentarios .
|
||||||
|
Windows Vista y versiones posteriores: Error (devolviendo 0 y estableciendo el último código de error en ERROR_NO_UNICODE_TRANSLATION) si se encuentra un carácter de entrada no válido. Puede recuperar el último código de error con una llamada a GetLastError. Si no se establece esta marca, la función reemplaza las secuencias no válidas por U+FFFD (codificada según corresponda para la página de códigos especificada) y se realiza correctamente devolviendo la longitud de la cadena convertida. Tenga en cuenta que esta marca solo se aplica cuando CodePage se especifica como CP_UTF8 o 54936. No se puede usar con otros valores de página de códigos. | ||||||
|
Traduce los caracteres Unicode que no se traducen directamente en equivalentes multibyte al carácter predeterminado especificado por lpDefaultChar. En otras palabras, si la traducción de Unicode a multibyte y de vuelta a Unicode de nuevo no produce el mismo carácter Unicode, la función usa el carácter predeterminado. Esta marca se puede usar por sí misma o en combinación con las demás marcas definidas.
En el caso de las cadenas que requieren validación, como los nombres de archivo, recurso y usuario, la aplicación siempre debe usar la marca WC_NO_BEST_FIT_CHARS. Esta marca impide que la función asigne caracteres a caracteres que aparecen similares, pero tienen una semántica muy diferente. En algunos casos, el cambio semántico puede ser extremo. Por ejemplo, el símbolo de "∞" (infinito) se asigna a 8 (ocho) en algunas páginas de códigos. |
Para las páginas de códigos que se enumeran a continuación, dwFlags debe ser 0. De lo contrario, se produce un error en la función con ERROR_INVALID_FLAGS.
- 50220
- 50221
- 50222
- 50225
- 50227
- 50229
- 57002 a 57011
- 65000 (UTF-7)
- 42 (símbolo)
[in] lpWideCharStr
Puntero a la cadena Unicode que se va a convertir.
[in] cchWideChar
Tamaño, en caracteres, de la cadena indicada por lpWideCharStr. Como alternativa, este parámetro se puede establecer en -1 si la cadena termina en null. Si cchWideChar está establecido en 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 de caracteres 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 de caracteres especificado. Si el tamaño proporcionado no incluye un carácter nulo de terminación, la cadena de caracteres resultante no termina en null y la longitud devuelta no incluye este carácter.
[out, optional] lpMultiByteStr
Puntero a un búfer que recibe la cadena convertida.
[in] cbMultiByte
Tamaño, en bytes, del búfer indicado por lpMultiByteStr. Si este valor es 0, la función devuelve el tamaño de búfer necesario, en bytes, incluido cualquier carácter nulo de terminación, y no usa el búfer lpMultiByteStr .
[in, optional] lpDefaultChar
Puntero al carácter que se va a usar si no se puede representar un carácter en la página de códigos especificada. La aplicación establece este parámetro en NULL si la función va a usar un valor predeterminado del sistema. Para obtener el carácter predeterminado del sistema, la aplicación puede llamar a la función GetCPInfo o GetCPInfoEx .
Para la configuración de CP_UTF7 y CP_UTF8 para CodePage, este parámetro debe establecerse en NULL. De lo contrario, se produce un error en la función ERROR_INVALID_PARAMETER.
[out, optional] lpUsedDefaultChar
Puntero a una marca que indica si la función ha usado un carácter predeterminado en la conversión. La marca se establece en TRUE si uno o varios caracteres de la cadena de origen no se pueden representar en la página de códigos especificada. De lo contrario, la marca se establece en FALSE. Este parámetro se puede establecer en NULL.
Para la configuración de CP_UTF7 y CP_UTF8 para CodePage, este parámetro debe establecerse en NULL. De lo contrario, se produce un error en la función ERROR_INVALID_PARAMETER.
Valor devuelto
Si se ejecuta correctamente, devuelve el número de bytes escritos en el búfer al que apunta lpMultiByteStr. Si la función se ejecuta correctamente y cbMultiByte es 0, el valor devuelto es el tamaño necesario, en bytes, para el búfer indicado por lpMultiByteStr. Consulte también dwFlags para obtener información sobre cómo afecta la marca de WC_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.
Comentarios
Los punteros lpMultiByteStr y lpWideCharStr no deben ser los mismos. Si son iguales, se produce un error en la función y GetLastError devuelve ERROR_INVALID_PARAMETER.
WideCharToMultiByte no termina en null 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 de la cadena de entrada.
Si cbMultiByte es menor que cchWideChar, esta función escribe el número de caracteres especificados por cbMultiByte en el búfer indicado por lpMultiByteStr. Sin embargo, si CodePage está establecido en CP_SYMBOL y cbMultiByte es menor que cchWideChar, la función no escribe caracteres en lpMultiByteStr.
La función WideCharToMultiByte funciona de forma más eficaz cuando lpDefaultChar y lpUsedDefaultChar se establecen en NULL. En la tabla siguiente se muestra el comportamiento de la función para las cuatro combinaciones posibles de estos parámetros.
| lpDefaultChar | lpUsedDefaultChar | Resultado |
|---|---|---|
| NULL | NULL | No hay ninguna comprobación predeterminada. Esta configuración de parámetros es la más eficaz para su uso con esta función. |
| Carácter que no es NULL | NULL | Usa el carácter predeterminado especificado, pero no establece lpUsedDefaultChar. |
| NULL | Carácter que no es NULL | Usa el carácter predeterminado del sistema y establece lpUsedDefaultChar si es necesario. |
| Carácter que no es NULL | Carácter que no es NULL | Usa el carácter predeterminado especificado y establece lpUsedDefaultChar si es necesario. |
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 innecesarias 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 encontrarse con problemas. Sin embargo, el código que usa esta función para generar cadenas UTF-8 válidas se comportará del mismo modo que en los sistemas operativos Windows anteriores.
A partir de Windows 8: WideCharToMultiByte se declara en Stringapiset.h. Antes de Windows 8, se declaró en Winnls.h.
WC_COMPOSITECHECK y marcas relacionadas
Como se describe en Uso de la normalización Unicode para representar cadenas, Unicode permite varias representaciones de la misma cadena (interpretadas lingüísticamente). Por ejemplo, capital A con dieresis (umlaut) se puede representar precomponida como un único punto de código Unicode "Ä" (U+00C4) o descomponido como la combinación de Mayúscula A y el carácter de dieresis combinado ("A" + " ́", que es U+0041 U+0308). Sin embargo, la mayoría de las páginas de códigos solo proporcionan caracteres compuestos.La marca WC_COMPOSITECHECK hace que la función WideCharToMultiByte pruebe los caracteres Unicode descomponidos e intenta redactarlos antes de convertirlos en la página de códigos solicitada. Esta marca solo está disponible para la conversión a páginas de códigos de byte único (SBCS) o de doble byte (DBCS) ( páginas < de códigos 50000, excepto la página de códigos 42). Si la aplicación necesita convertir datos Unicode descomponidos en páginas de códigos de un solo byte o doble byte, esta marca podría ser útil. Sin embargo, no todos los caracteres se pueden convertir de esta manera y es más confiable guardar y almacenar datos como Unicode.
Cuando una aplicación usa WC_COMPOSITECHECK, algunas combinaciones de caracteres pueden permanecer incompletas o pueden tener caracteres adicionales que no tienen espacio restante. Por ejemplo, A + ́ + ́ combina con Ä + ́. El uso de la marca WC_DISCARDNS hace que la función descarte caracteres adicionales sin espacio. El uso de la marca WC_DEFAULTCHAR hace que la función use el carácter de reemplazo predeterminado (normalmente "?") en su lugar. El uso de la marca WC_SEPCHARS hace que la función intente convertir cada carácter adicional sin espacio en la página de códigos de destino. Normalmente, esta marca también provoca el uso del carácter de reemplazo ("?"). Sin embargo, para la página de códigos 1258 (vietnamita) y 20269, existen caracteres sin espaciado y se pueden usar. Las conversiones de estas páginas de códigos no son perfectas. Algunas combinaciones no se convierten correctamente en la página de códigos 1258 y WC_COMPOSITECHECK daña los datos de la página de códigos 20269. Como se mencionó anteriormente, es más confiable diseñar la aplicación para guardar y almacenar datos como Unicode.
Ejemplos
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
| 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