Función GetLocaleInfoA (winnls.h)

Artículo
03/08/2023

Recupera información sobre una configuración regional especificada por el identificador.

Nota Por motivos de interoperabilidad, la aplicación debe preferir la función GetLocaleInfoEx a GetLocaleInfo 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. Cualquier aplicación que se ejecute solo en Windows Vista y versiones posteriores debe usar GetLocaleInfoEx.

Nota Para la compatibilidad global, la aplicación debe preferir los formularios de LA API "W" unicode a los formularios "A". GetLocaleInfoA limitará los datos de caracteres y podría dar lugar a resultados que aparecen dañados para los usuarios, especialmente en aplicaciones habilitadas globalmente. Para esta API, se prefiere GetLocaleInfoEx , ya que es Unicode y también admite estándares de nombres de configuración regional modernos.

Sintaxis

int GetLocaleInfoA(
  [in]            LCID   Locale,
  [in]            LCTYPE LCType,
  [out, optional] LPSTR  lpLCData,
  [in]            int    cchData
);

Parámetros

[in] Locale

Identificador de configuración regional para el que se va a recuperar información. Puede usar la macro MAKELCID para crear un identificador de configuración regional o usar uno de los siguientes valores predefinidos.

[in] LCType

Información de configuración regional que se va a recuperar. Para obtener definiciones detalladas, consulte el parámetro LCType de GetLocaleInfoEx.

Nota Para GetLocaleInfo, el valor LOCALE_USE_CP_ACP solo es relevante para la versión ansi.

[out, optional] lpLCData

Puntero a un búfer en el que esta función recupera la información de configuración regional solicitada. Este puntero no se usa si cchData está establecido en 0. Para obtener más información, vea la sección Comentarios.

[in] cchData

Tamaño, en valores TCHAR, del búfer de datos indicado por lpLCData. Como alternativa, la aplicación puede establecer este parámetro en 0. En este caso, la función no usa el parámetro lpLCData y devuelve el tamaño de búfer necesario, incluido el carácter nulo de terminación.

Valor devuelto

Devuelve el número de caracteres recuperados en el búfer de datos de configuración regional si es correcto y cchData es un valor distinto de cero. Si la función se ejecuta correctamente, cchData es distinto de cero y se especifica LOCALE_RETURN_NUMBER , el valor devuelto es el tamaño del entero recuperado en el búfer de datos; es decir, 2 para la versión Unicode de la función o 4 para la versión ANSI. Si la función se ejecuta correctamente y el valor de cchData es 0, el valor devuelto es el tamaño necesario, en caracteres, incluido un carácter nulo, para el búfer de datos de configuración regional.

La 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

Para el funcionamiento de esta función, vea Comentarios para GetLocaleInfoEx.

Nota Incluso cuando el parámetro LCType se especifica como LOCALE_FONTSIGNATURE, cchData y la función devuelta siguen siendo recuentos de TCHAR. El recuento es diferente para las versiones ANSI y Unicode de la función. Cuando una aplicación llama a la versión genérica de GetLocaleInfo con LOCALE_FONTSIGNATURE, cchData se puede especificar de forma segura como sizeof(LOCALESIGNATURE) / sizeof(TCHAR).

Los ejemplos siguientes tratan correctamente el tamaño del búfer para los valores que no son de texto:

int   ret;
CALID calid;
DWORD value;

ret = GetLocaleInfo(LOCALE_USER_DEFAULT,
                    LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                    (LPTSTR)&value,
                    sizeof(value) / sizeof(TCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

ret = GetLocaleInfo(LOCALE_USER_DEFAULT,
                    LOCALE_FONTSIGNATURE,
                    (LPWSTR)&LocSig,
                    sizeof(LocSig) / sizeof(TCHAR) );

La cadena ANSI recuperada por la versión ANSI de esta función se traduce de Unicode a ANSI en función de la página de códigos ANSI predeterminada para el identificador de configuración regional. Sin embargo, si se especifica LOCALE_USE_CP_ACP , la traducción se basa en la página de códigos ANSI predeterminada del sistema.

Cuando la versión ANSI de esta función se usa con un identificador de configuración regional solo Unicode, la función puede realizarse correctamente porque el sistema operativo usa la página de códigos 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 GetLocaleInfo 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 Convenciones para prototipos de función.

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows 2000 Server [aplicaciones de escritorio \| Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winnls.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll