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.

• LOCALE_INVARIANT
• LOCALE_SYSTEM_DEFAULT
• LOCALE_USER_DEFAULT

• LOCALE_CUSTOM_DEFAULT
• LOCALE_CUSTOM_UI_DEFAULT
• LOCALE_CUSTOM_UNSPECIFIED

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

[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 (?).

Requisitos

Vea también

CompareString

FindNLSString

GetNLSVersion

Control de la ordenación en las aplicaciones

LCMapStringEx

Compatibilidad con idiomas nacionales

Funciones de compatibilidad con idiomas nacionales