Función LCMapStringA (winnls.h)
Para una configuración regional especificada por identificador, 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 LCMapStringA(
[in] LCID Locale,
[in] DWORD dwMapFlags,
[in] LPCSTR lpSrcStr,
[in] int cchSrc,
[out, optional] LPSTR lpDestStr,
[in] int cchDest
);
Parámetros
[in] Locale
Identificador de configuración regional que especifica la configuración regional. Puede usar la macro MAKELCID para crear un identificador de configuración regional o usar uno de los siguientes valores predefinidos.
También se admiten los siguientes identificadores de configuración regional personalizados.[in] dwMapFlags
Marcas que especifican 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. Para obtener definiciones detalladas, consulte el parámetro dwMapFlags de LCMapStringEx.
[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 el parámetro en cualquier valor negativo para especificar que la cadena de origen está terminada en null. En este caso, si LCMapString 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.
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 realiza correctamente cuando se usa para la asignación de cadenas, 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.
- 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
Vea Comentarios para LCMapStringEx.
La versión ANSI de LCMapString asigna cadenas hacia y desde Unicode según la página de códigos predeterminada de Windows (ANSI) asociada a la configuración regional especificada. Cuando se usa la versión ANSI de esta función con una configuración regional solo Unicode, la función puede realizarse correctamente porque el sistema operativo usa el valor de CP_ACP, que representa la página de códigos ANSI de Windows predeterminada del sistema. Sin embargo, los caracteres que no están definidos en la página de códigos del sistema aparecen en la cadena como signo de interrogación (?).
Nota
El encabezado winnls.h define LCMapString como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
| Cliente mínimo compatible | Windows 2000 Professional [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows 2000 Server [solo aplicaciones de escritorio] |
| 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