Expand Minimize

GetLocaleInfoEx function

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_opt_   LPCWSTR lpLocaleName,
  _In_       LCTYPE LCType,
  _Out_opt_  LPWSTR lpLCData,
  _In_       int cchData
);

Parameters

lpLocaleName [in, optional]

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

LCType [in]

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.

lpLCData [out, optional]

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

cchData [in]

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.

Windows Phone 8: This API is supported.

Windows Phone 8.1: This API is supported.

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

Minimum supported client

Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 [desktop apps | Windows Store apps]

Header

Winnls.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

National Language Support
National Language Support Functions
Retrieving and Setting Locale Information
GetLocaleInfo
GetSystemDefaultLocaleName
GetUserDefaultLocaleName
SetLocaleInfo

 

 

Community Additions

ADD
Show:
© 2014 Microsoft