GetLocaleInfoEx function (winnls.h)

Article
10/13/2021

Retrieves information about a locale specified by name.

Note The application should call this function in preference to GetLocaleInfo if designed to run only on Windows Vista and later.

Note This function can retrieve data that changes between releases, for example, due to a custom locale. If your application must persist or transmit data, see Using Persistent Locale Data.

Syntax

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

Parameters

[in, optional] lpLocaleName

Pointer to a locale name, or one of the following predefined values.

[in] LCType

The locale information to retrieve. For possible values, see the "Constants Used in the LCType Parameter of GetLocaleInfo, GetLocaleInfoEx, and SetLocaleInfo" section in Locale Information Constants. Note that only one piece of locale information can be specified per call.

The application can use the binary OR operator to combine LOCALE_RETURN_NUMBER with any other allowed constant. In this case, the function retrieves the value as a number instead of a string. The buffer that receives the value must be at least the length of a DWORD value, which is 2.

Caution It is also possible to combine LOCALE_NOUSEROVERRIDE with any other constant. However, use of this constant is strongly discouraged. (Even without using the current user override, the data can differ from computer to computer, and custom locales can change the data. For example, even month or day names are subject to spelling reforms.)

If LCType is set to LOCALE_IOPTIONALCALENDAR, the function retrieves only the first alternate calendar.

Note To get all alternate calendars, the application should use EnumCalendarInfoEx.

Starting with Windows Vista, your applications should not use LOCALE_ILANGUAGE in the LCType parameter to avoid failure or retrieval of unexpected data. Instead, it is recommended for your applications to call GetLocaleInfoEx.

[out, optional] lpLCData

Pointer to a buffer in which this function retrieves the requested locale information. This pointer is not used if cchData is set to 0.

[in] cchData

Size, in characters, of the data buffer indicated by lpLCData. Alternatively, the application can set this parameter to 0. In this case, the function does not use the lpLCData parameter and returns the required buffer size, including the terminating null character.

Return value

Returns the number of characters retrieved in the locale data buffer if successful and cchData is a nonzero value. If the function succeeds, cchData is nonzero, and LOCALE_RETURN_NUMBER is specified, the return value is the size of the integer retrieved in the data buffer, that is, 2. If the function succeeds and the value of cchData is 0, the return value is the required size, in characters including a null character, for the locale data buffer.

The function returns 0 if it does not succeed. To get extended error information, the application can call GetLastError, which can return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER. A supplied buffer size was not large enough, or it was incorrectly set to NULL.
ERROR_INVALID_FLAGS. The values supplied for flags were not valid.
ERROR_INVALID_PARAMETER. Any of the parameter values was invalid.

Remarks

This function normally retrieves information in text format. If the information is a numeric value and the value of LCType is LOCALE_ILANGUAGE or LOCALE_IDEFAULTLANGUAGE, this function retrieves strings containing hexadecimal numbers. Otherwise, the retrieved text for numeric information is a decimal number.

There are two exceptions to this rule. First, the application can retrieve numeric values as integers by specifying LOCALE_RETURN_NUMBER in the LCType parameter. The second exception is that LOCALE_FONTSIGNATURE behaves differently from all other locale information constants. The application must provide a data buffer of at least sizeof(LOCALESIGNATURE) bytes. On successful return from the function, the buffer is filled in as a LOCALESIGNATURE structure.

Note Even when the LCType parameter is specified as LOCALE_FONTSIGNATURE, cchData and the function return are still character counts. When an application calls GetLocaleInfoEx with LCType specified as LOCALE_FONTSIGNATURE, cchData can be safely specified as sizeof(LOCALESIGNATURE) / sizeof(WCHAR).

The following examples deal correctly with the buffer size for non-text values:

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) );

This function can retrieve data from custom locales. Data is not guaranteed to be the same from computer to computer or between runs of an application. If your application must persist or transmit data, see Using Persistent Locale Data.

Beginning in Windows 8: If your app passes language tags to this function from the Windows.Globalization namespace, it must first convert the tags by calling ResolveLocaleName.

Examples

Examples showing the use of this function can be found in NLS: Name-based APIs Sample and NLS: Internationalized Domain Name (IDN) Mitigation Sample.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 [desktop apps \| UWP apps]
Target Platform	Windows
Header	winnls.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

Share via