Función LCMapStringEx (winnls.h)

Artículo
03/08/2023

Para una configuración regional especificada por nombre, asigna una cadena de caracteres de entrada a otra mediante una transformación especificada o genera una clave de ordenación para la cadena de entrada.

Nota La aplicación debe llamar a esta función en preferencia a LCMapString si está diseñada para ejecutarse solo en Windows Vista y versiones posteriores.

Sintaxis

int LCMapStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwMapFlags,
  [in]            LPCWSTR          lpSrcStr,
  [in]            int              cchSrc,
  [out, optional] LPWSTR           lpDestStr,
  [in]            int              cchDest,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

Parámetros

[in, optional] lpLocaleName

Puntero a un nombre de configuración regional o uno de los siguientes valores predefinidos.

[in] dwMapFlags

Marca que especifica el tipo de transformación que se va a usar durante la asignación de cadenas o el tipo de clave de ordenación que se va a generar. Este parámetro puede tener los valores siguientes.

Marca	Significado
LCMAP_BYTEREV	Use inversión de bytes. Por ejemplo, si la aplicación pasa 0x3450 0x4822, el resultado es 0x5034 0x2248.
LCMAP_FULLWIDTH	Use caracteres Unicode (anchos) cuando corresponda. Esta marca y LCMAP_HALFWIDTH son mutuamente excluyentes. Con esta marca, la asignación puede usar el formulario de normalización C incluso si un carácter de entrada ya tiene ancho completo. Por ejemplo, la cadena "は゛" (que ya es de ancho completo) se normaliza a "ば". Vea Unicode normalization forms (Formas de normalización Unicode).
LCMAP_HALFWIDTH	Use caracteres estrechos cuando corresponda. Esta marca y LCMAP_FULLWIDTH son mutuamente excluyentes.
LCMAP_HIRAGANA	Asigne todos los caracteres katakana a hiragana. Esta marca y LCMAP_KATAKANA son mutuamente excluyentes.
LCMAP_KATAKANA	Asigne todos los caracteres hiragana a katakana. Esta marca y LCMAP_HIRAGANA son mutuamente excluyentes.
LCMAP_LINGUISTIC_CASING	Use reglas lingüísticas para el uso de mayúsculas y minúsculas, en lugar de las reglas del sistema de archivos (valor predeterminado). Esta marca solo es válida con LCMAP_LOWERCASE o LCMAP_UPPERCASE.
LCMAP_LOWERCASE	Para configuraciones regionales y scripts capaces de controlar mayúsculas y minúsculas, asigne todos los caracteres a minúsculas.
LCMAP_HASH	Devuelve un hash de los pesos de ordenación sin formato de una cadena. Las cadenas que aparecen equivalentes suelen devolver el mismo hash (por ejemplo, "hello" y "HELLO" con LCMAP_IGNORECASE). Sin embargo, algunos casos complejos, como los idiomas del Este asiático, pueden tener cadenas similares con pesos idénticos que se comparan como iguales, pero no devuelven el mismo hash. LCMAP_HASH requiere que el búfer de salida sea de sizeof(int)
LCMAP_SIMPLIFIED_CHINESE	Asigne caracteres chinos tradicionales a caracteres chinos simplificados. Esta marca y LCMAP_TRADITIONAL_CHINESE son mutuamente excluyentes.
LCMAP_SORTHANDLE El uso de un identificador de ordenación da como resultado mejoras de rendimiento mínimas y no se recomienda.	Devuelve un token que representa los parámetros de ordenación resueltos para la configuración regional (como el nombre de la configuración regional), por lo que las llamadas futuras pueden pasar `NULL` para el nombre de ordenación y pasar el identificador de ordenación consultado anteriormente como el último parámetro (sortHandle) en llamadas posteriores a CompareStringEx o LCMapStringEx. LCMAP_SORTHANDLE requiere que el búfer de salida sea de tamañoof(lparam)
LCMAP_SORTKEY	Genera una clave de ordenación normalizada. Si no se especifica la marca LCMAP_SORTKEY, la función realiza la asignación de cadenas. Para obtener más información sobre la generación de claves de ordenación y la asignación de cadenas, consulte la sección Comentarios.
LCMAP_TITLECASE	Windows 7: asigne todos los caracteres al caso de título, en el que se escribe en mayúsculas la primera letra de cada palabra principal.
LCMAP_TRADITIONAL_CHINESE	Asignar caracteres chinos simplificados a caracteres chinos tradicionales. Esta marca y LCMAP_SIMPLIFIED_CHINESE son mutuamente excluyentes.
LCMAP_UPPERCASE	Para configuraciones regionales y scripts capaces de controlar mayúsculas y minúsculas, asigne todos los caracteres a mayúsculas.

Las marcas siguientes se pueden usar solas, entre sí o con las marcas LCMAP_SORTKEY o LCMAP_BYTEREV. Sin embargo, no se pueden combinar con las otras marcas enumeradas anteriormente.

Marca	Significado
NORM_IGNORENONSPACE	Omitir caracteres sin espaciado. Para muchos scripts (en particular alfabetos latinos), NORM_IGNORENONSPACE coincide con LINGUISTIC_IGNOREDIACRITIC. Nota NORM_IGNORENONSPACE omite cualquier distinción secundaria, ya sea diacrítica o no. Los scripts para idiomas coreanos, japoneses, chinos e indices, entre otros, usan esta distinción con fines distintos de los diacríticos. LINGUISTIC_IGNOREDIACRITIC hace que la función ignore solo los diacríticos reales, en lugar de omitir el segundo peso de ordenación.
NORM_IGNORESYMBOLS	Omitir símbolos y puntuación.

Marca

Significado

NORM_IGNORENONSPACE

Omitir caracteres sin espaciado. Para muchos scripts (en particular alfabetos latinos), NORM_IGNORENONSPACE coincide con LINGUISTIC_IGNOREDIACRITIC.

Nota NORM_IGNORENONSPACE omite cualquier distinción secundaria, ya sea diacrítica o no. Los scripts para idiomas coreanos, japoneses, chinos e indices, entre otros, usan esta distinción con fines distintos de los diacríticos. LINGUISTIC_IGNOREDIACRITIC hace que la función ignore solo los diacríticos reales, en lugar de omitir el segundo peso de ordenación.

NORM_IGNORESYMBOLS

Omitir símbolos y puntuación.

Las marcas que se enumeran a continuación solo se usan con la marca LCMAP_SORTKEY.

Marca	Significado
LINGUISTIC_IGNORECASE	Omita mayúsculas y minúsculas, según corresponda lingüísticamente.
LINGUISTIC_IGNOREDIACRITIC	Omita los caracteres sin espaciar, según corresponda lingüísticamente. Nota Esta marca no siempre genera resultados predecibles cuando se usan con caracteres descomponidos, es decir, caracteres en los que un carácter base y uno o varios caracteres sin espaciado tienen valores de punto de código distintos.
NORM_IGNORECASE	Omitir mayúsculas y minúsculas. Para muchos scripts (en particular los alfabetos latinos), NORM_IGNORECASE coincide con LINGUISTIC_IGNORECASE. Nota NORM_IGNORECASE omite cualquier distinción terciaria, ya sea en realidad lingüística o no. Por ejemplo, en alfabetos árabes e indices, esta marca distingue las formas alternativas de un carácter, pero las diferencias no corresponden a mayúsculas y minúsculas lingüísticas. LINGUISTIC_IGNORECASE hace que la función omita solo mayúsculas y minúsculas lingüísticas reales, en lugar de omitir el tercer peso de ordenación. Nota En las configuraciones regionales del juego de caracteres de doble byte (DBCS), NORM_IGNORECASE tiene un efecto en todos los caracteres Unicode, así como en caracteres estrechos (un byte), incluidos los caracteres griegos y cirílicos.
NORM_IGNOREKANATYPE	No diferencie entre caracteres hiragana y katakana. Los caracteres hiragana y katakana correspondientes se comparan como iguales.
NORM_IGNOREWIDTH	Omita la diferencia entre los caracteres de ancho medio y ancho completo, por ejemplo, C a t == cat. El formato de ancho completo es una distinción de formato que se usa en scripts chinos y japoneses.
NORM_LINGUISTIC_CASING	Use reglas lingüísticas para el uso de mayúsculas y minúsculas, en lugar de las reglas del sistema de archivos (valor predeterminado).
SORT_DIGITSASNUMBERS	Windows 7: Trate los dígitos como números durante la ordenación, por ejemplo, ordene "2" antes de "10".
SORT_STRINGSORT	Trate la puntuación igual que los símbolos.

[in] lpSrcStr

Puntero a una cadena de origen que la función asigna o usa para la generación del criterio de ordenación. Esta cadena no puede tener un tamaño de 0.

[in] cchSrc

Tamaño, en caracteres, de la cadena de origen indicada por lpSrcStr. El tamaño de la cadena de origen puede incluir el carácter nulo de terminación, pero no tiene que hacerlo. Si se incluye el carácter NULO de terminación, el comportamiento de asignación de la función no se ve afectado en gran medida porque el carácter nulo de terminación se considera que no se puede clasificar y siempre se asigna a sí mismo.

La aplicación puede establecer este parámetro en cualquier valor negativo para especificar que la cadena de origen está terminada en null. En este caso, si LCMapStringEx se usa en su modo de asignación de cadenas, la función calcula la propia longitud de cadena y finaliza la cadena asignada indicada por lpDestStr.

La aplicación no puede establecer este parámetro en 0.

[out, optional] lpDestStr

Puntero a un búfer en el que esta función recupera la cadena asignada o una clave de ordenación.

Si la aplicación usa la función para generar una clave de ordenación (LCMAP_SORTKEY):

La clave de ordenación se almacena en el búfer y se trata como una matriz opaca de bytes. Los valores almacenados pueden incluir 0 bytes incrustados en cualquier posición.
La cadena de destino puede contener un número impar de bytes. La marca LCMAP_BYTEREV solo invierte un número par de bytes. El último byte (en posición impar) de la clave de ordenación no se invierte.

Si el autor de la llamada solicita explícitamente un subconjunto de la cadena, la cadena de destino no incluye un carácter nulo de terminación a menos que el autor de la llamada lo especifique en cchDest.

Si se produce un error en esta función, el búfer de destino puede contener resultados parciales o ningún resultado. En este caso, todos los resultados deben considerarse no válidos.

Nota

Al establecer LCMAP_UPPERCASE o LCMAP_LOWERCASE, la cadena de destino puede usar el mismo búfer que la cadena de origen. Sin embargo, esto no se recomienda, ya que algunas condiciones pueden hacer que la cadena con mayúsculas y minúsculas devuelta sea de una longitud diferente.

[in] cchDest

Tamaño, en caracteres, de la cadena de destino indicada por lpDestStr. Si la aplicación usa la función para la asignación de cadenas, proporciona un recuento de caracteres para este parámetro. Si el espacio para un carácter nulo de terminación se incluye en cchSrc, cchDest también debe incluir espacio para un carácter nulo de terminación.

Si la aplicación usa la función para generar una clave de ordenación, proporciona un recuento de bytes para el tamaño. Este recuento de bytes debe incluir espacio para la clave de ordenación 0x00 terminador.

La aplicación puede establecer cchDest en 0. En este caso, la función no usa el parámetro lpDestStr y devuelve el tamaño de búfer necesario para la cadena asignada o clave de ordenación.

[in, optional] lpVersionInformation

Puntero a una estructura NLSVERSIONINFOEX que contiene la información de versión sobre la funcionalidad NLS pertinente; normalmente recuperado de GetNLSVersionEx.

Windows Vista, Windows 7: Reservados; debe establecerse en NULL.

[in, optional] lpReserved

Reservados; debe ser NULL.

[in, optional] sortHandle

Reservados; debe ser 0.

Nota

CompareStringEx y LCMapStringEx pueden especificar un identificador de ordenación (si el nombre de la configuración regional es null). Este uso no se recomienda para la mayoría de las aplicaciones.

Valor devuelto

Si la función se ejecuta correctamente cuando se usa para la asignación de cadenas, devuelve el número de caracteres de la cadena traducida (consulte cchSrc y cchDest para obtener más detalles).

Si la función se ejecuta correctamente cuando se usa para generar una clave de ordenación, devuelve el número de bytes de la clave de ordenación.

Esta 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.

Comentarios

La aplicación puede usar LCMapString o LCMapStringEx para generar una clave de ordenación. Para ello, la aplicación especifica LCMAP_SORTKEY para el parámetro dwMapFlags . Para obtener más información, consulte Control de la ordenación en las aplicaciones.

Nota

Las claves de ordenación son secuencias de bytes opacas. Los autores de llamadas deben tratarlos como una matriz de bytes de la longitud devuelta por la API y no depender de ninguna estructura interna que parezca estar presente. Cero, uno o varios de los bytes de la clave de ordenación devuelta podrían ser 0. No se debe esperar la ausencia o presencia de un byte cero.

Otra manera de que la aplicación use LCMapString o LCMapStringEx es en cadenas de asignación. En este caso, la aplicación no especifica LCMAP_SORTKEY para el parámetro dwMapFlags , pero proporciona alguna otra combinación de marcas. Para obtener más información, consulte Control de la ordenación en las aplicaciones.

A partir de Windows Vista: Esta función puede controlar los datos de configuraciones regionales personalizadas. No se garantiza que los datos sean los mismos desde el equipo al equipo o entre ejecuciones de una aplicación. Si la aplicación debe conservar o transmitir datos, consulte Uso de datos de configuración regional persistente.

A partir de Windows 8: si la aplicación pasa etiquetas de idioma a esta función desde el espacio de nombres Windows.Globalization, primero debe convertir las etiquetas llamando a ResolveLocaleName.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winnls.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll