Función GetLocaleInfoEx (winnls.h)

Artículo
03/08/2023

Recupera información sobre una configuración regional especificada por nombre.

Nota La aplicación debe llamar a esta función en preferencia a GetLocaleInfo si está diseñada para ejecutarse solo en Windows Vista y versiones posteriores.

Nota Esta función puede recuperar datos que cambian entre versiones, por ejemplo, debido a una configuración regional personalizada. Si la aplicación debe conservar o transmitir datos, consulte Uso de datos de configuración regional persistente.

Sintaxis

int GetLocaleInfoEx(
  [in, optional]  LPCWSTR lpLocaleName,
  [in]            LCTYPE  LCType,
  [out, optional] LPWSTR  lpLCData,
  [in]            int     cchData
);

Parámetros

[in, optional] lpLocaleName

Puntero a un nombre de configuración regional o uno de los siguientes valores predefinidos.

[in] LCType

Información de configuración regional que se va a recuperar. Para obtener los valores posibles, vea la sección "Constantes usadas en el parámetro LCType de GetLocaleInfo, GetLocaleInfoEx y SetLocaleInfo" en Constantes de información regional. Tenga en cuenta que solo se puede especificar un fragmento de información regional por llamada.

La aplicación puede usar el operador OR binario para combinar LOCALE_RETURN_NUMBER con cualquier otra constante permitida. En este caso, la función recupera el valor como un número en lugar de una cadena. El búfer que recibe el valor debe ser al menos la longitud de un valor DWORD, que es 2.

Precaución También es posible combinar LOCALE_NOUSEROVERRIDE con cualquier otra constante. Sin embargo, se desaconseja encarecidamente el uso de esta constante. (Incluso sin usar la invalidación del usuario actual, los datos pueden diferir del equipo al equipo, y las configuraciones regionales personalizadas pueden cambiar los datos. Por ejemplo, incluso los nombres de mes o día están sujetos a reformas ortográficas.

Si LCType se establece en LOCALE_IOPTIONALCALENDAR, la función recupera solo el primer calendario alternativo.

Nota Para obtener todos los calendarios alternativos, la aplicación debe usar EnumCalendarInfoEx.

A partir de Windows Vista, las aplicaciones no deben usar LOCALE_ILANGUAGE en el parámetro LCType para evitar errores o recuperación de datos inesperados. En su lugar, se recomienda que las aplicaciones llamen a GetLocaleInfoEx.

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

[in] cchData

Tamaño, en caracteres, 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. 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

Esta función normalmente recupera información en formato de texto. Si la información es un valor numérico y el valor de LCType es LOCALE_ILANGUAGE o LOCALE_IDEFAULTLANGUAGE, esta función recupera cadenas que contienen números hexadecimales. De lo contrario, el texto recuperado para la información numérica es un número decimal.

Existen dos excepciones a esta regla. En primer lugar, la aplicación puede recuperar valores numéricos como enteros especificando LOCALE_RETURN_NUMBER en el parámetro LCType . La segunda excepción es que LOCALE_FONTSIGNATURE se comporta de forma diferente de todas las demás constantes de información regional. La aplicación debe proporcionar un búfer de datos de al menos sizeof(LOCALESIGNATURE). Si la función se devuelve correctamente, el búfer se rellena como una estructura LOCALESIGNATURE .

Nota Incluso cuando el parámetro LCType se especifica como LOCALE_FONTSIGNATURE, cchData y la función devuelta siguen siendo recuentos de caracteres. Cuando una aplicación llama a GetLocaleInfoEx con LCType especificado como LOCALE_FONTSIGNATURE, cchData se puede especificar de forma segura como sizeof(LOCALESIGNATURE) / sizeof(WCHAR).

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 = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                      (LPWSTR)&value,
                      sizeof(value) / sizeof(WCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

ret = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_FONTSIGNATURE,
                      (LPWSTR)&LocSig,
                      sizeof(LocSig) / sizeof(WCHAR) );

Esta función puede recuperar 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 mediante una llamada a ResolveLocaleName.

Ejemplos

Ejemplos que muestran el uso de esta función se pueden encontrar en NLS: Ejemplo de API basadas en nombres y NLS: Ejemplo de mitigación de nombres de dominio internacionalizados (IDN).

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 (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll