Compartir a través de


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.

Precaución El uso incorrecto de la función WideCharToMultiByte 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 lpWideCharStr es igual al número de caracteres de la cadena Unicode, mientras que el tamaño del búfer de salida indicado por lpMultiByteStr es igual al número de bytes. 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.

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.

 
Nota Las páginas de códigos ANSI pueden ser diferentes en equipos diferentes o pueden cambiarse para un único 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 o formatos de datos heredados 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 los archivos de texto no.
 

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.

Valor Significado
CP_ACP
Página de códigos de Windows ANSI 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 irrecuperablemente dañados. 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 actual de Macintosh 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 irrecuperablemente dañados. 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 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 irrecuperablemente dañados. Este valor solo está pensado para uso temporal y el almacenamiento permanente debe usar UTF-16 o UTF-8 si es posible.
 
CP_SYMBOL
Windows 2000: Página de códigos de símbolos (42).
CP_THREAD_ACP
Windows 2000: 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 irrecuperablemente dañados. 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. Con este conjunto de valores, lpDefaultChar y lpUsedDefaultChar deben establecerse en NULL.
CP_UTF8
UTF-8. Con este conjunto de valores, lpDefaultChar y lpUsedDefaultChar deben establecerse en NULL.

[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
WC_COMPOSITECHECK
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 .

WC_DEFAULTCHAR Reemplace las excepciones por el carácter predeterminado durante la conversión.
WC_DISCARDNS Descartar caracteres sin espaciado durante la conversión.
WC_SEPCHARS Predeterminada. Generar caracteres independientes durante la conversión.
 
WC_ERR_INVALID_CHARS
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.
WC_NO_BEST_FIT_CHARS
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)
Nota Para la página de códigos 65001 (UTF-8) o la página de códigos 54936 (GB18030, Windows Vista y versiones posteriores), dwFlags debe establecerse en 0 o WC_ERR_INVALID_CHARS. De lo contrario, se produce un error en la función con ERROR_INVALID_FLAGS.
 

[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

MultiByteToWideChar

Funciones Unicode y Juego de caracteres

Conjuntos de caracteres y Unicode

API de Vertdll disponibles en enclaves de VBS