Función LCMapStringEx (winnls.h)
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.
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.
Las marcas que se enumeran a continuación solo se usan con la marca LCMAP_SORTKEY.
[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 |
Vea también
Control de la ordenación en las aplicaciones