Función LCMapStringA (winnls.h)

Artículo
11/20/2024

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.

Nota Por motivos de interoperabilidad, la aplicación debe preferir la función LCMapStringEx para LCMapString porque Microsoft está migrando hacia el uso de nombres de configuración regional en lugar de identificadores de configuración regional para nuevas configuraciones regionales. Esta recomendación se aplica especialmente a las configuraciones regionales personalizadas, incluidas las creadas por Microsoft. Cualquier aplicación que se ejecute solo en Windows Vista y versiones posteriores debe usar LCMapStringEx.

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 de claves 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 dividir 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 null 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 encarecidamente, ya que algunas condiciones pueden hacer que la cadena de mayúsculas y minúsculas devuelta sea 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 se incluye espacio para un carácter NULO de terminación 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 la 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 (vea cchSrc y cchDest para obtener más detalles).

Si la función se ejecuta 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.

Observaciones

Vea los comentarios de 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 de 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winnls.h (incluya Windows.h)
biblioteca de	Kernel32.lib
DLL de	Kernel32.dll