Welcome Sign in
Microsoft Developer Network
Click to Rate and Give Feedback
MSDN
MSDN Library
User Interface
 GetLocaleInfo
International Features
GetLocaleInfo

Retrieves information about a locale specified by identifier.

Note: This function retrieves information only about a locale specified by identifier. Additional locales, features, and RFC 4646 names are supported by the GetLocaleInfoEx function.

int GetLocaleInfo(
  LCID Locale,     
  LCTYPE LCType,    
  LPTSTR lpLCData,  
  int cchData       
);

Parameters

Locale
[in] Locale identifier for which to retrieve information. You can use the MAKELCID macro to create a locale identifier or use one of the following predefined values. For more information, see Locale Identifier Constants and Strings.
  • LOCALE_INVARIANT
  • LOCALE_SYSTEM_DEFAULT
  • LOCALE_USER_DEFAULT

Windows Vista and later: The following custom locale identifiers are also supported.

  • LOCALE_CUSTOM_DEFAULT
  • LOCALE_CUSTOM_UI_DEFAULT
  • LOCALE_CUSTOM_UNSPECIFIED
LCType
[in] Type of locale information to retrieve. For a list of possible values, see LCTYPE Constants (National Language Support). Note that only one locale identifier can be specified per call. However, the application can use the binary OR operator to combine LOCALE_NOUSEROVERRIDE or LOCALE_USE_CP_ACP with any other constant.

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

Windows 98/Me, Windows NT 4.0 and later: The application can combine LOCALE_RETURN_NUMBER with a locale constant beginning with LOCALE_I.

If LOCALE_NOUSEROVERRIDE is combined with another constant, the function bypasses user overrides, and retrieves the system default value for the specified locale identifier. If this constant is not specified, the function formats the string using any user overrides to the locale's default information format. Note: Since LOCALE_NOUSEROVERRIDE disables user preferences, its use is discouraged.

LOCALE_USE_CP_ACP is relevant only for the ANSI version of this function.

If LOCALE_RETURN_NUMBER is combined with another value, 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.

lpLCData
[out] Pointer to a buffer in which this function retrieves the requested locale information. This pointer is not used if cchData is set to 0. For more information, see the Remarks section.
cchData
[in] Size, in TCHAR values, 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 Values

Returns the number of characters retrieved in the locale data buffer if successful and cchData is a nonzero value. If the function succeeds and 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 for the Unicode version of the function or 4 for the ANSI version. 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. GetLastError can return one of the following error codes:

  • ERROR_INSUFFICIENT_BUFFER
  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

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 returned 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 TCHAR counts. The count is different for the ANSI and Unicode versions of the function. When an application calls the generic version of GetLocaleInfo with LOCALE_FONTSIGNATURE, cchData can be safely specified as sizeof(LOCALESIGNATURE)/sizeof(TCHAR).

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

int ret;
CALID calid;
	ret = GetLocaleInfo( LOCALE_USER_DEFAULT,
               LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
               (LPWSTR)&calid;,
               sizeof(calid) / sizeof(TCHAR) );

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

The ANSI string retrieved by the ANSI version of this function is translated from Unicode to ANSI based on the default ANSI code page for the locale identifier. However, if LOCALE_USE_CP_ACP is specified, the translation is based on the system default ANSI code page.

If LCType is set to LOCALE_IOPTIONALCALENDAR, GetLocaleInfo retrieves only the first alternate calendar. To get all alternate calendars, the application should use EnumCalendarInfo.

Note: When the ANSI version of this function is used with a Unicode-only locale identifier, the function can succeed because the operating system uses the system code page. However, characters that are undefined in the system code page appear in the string as a question mark (?). To determine the identifiers that are Unicode-only, see Locale Identifier Constants and Strings.

Windows 95/98/Me: The Unicode version of this function is supported by the Microsoft Layer for Unicode. To use this version, you must add certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems.

This function can retrieve data from custom locales. Locales are 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.

Applications that run only on Windows Vista and later should use GetLocaleInfoEx in preference to this function. GetLocaleInfoEx provides good support for supplemental locales. However, GetLocaleInfoEx is not supported for versions of Windows prior to Windows Vista.

Requirements

  Windows NT/2000/XP/Vista: Included in Windows NT 3.1 and later.
  Windows 95/98/Me: Included in Windows 95 and later.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP. Also supported by Microsoft Layer for Unicode.
  Header: Declared in Winnls.h; include Windows.h.
  Library: Use Kernel32.lib.

See Also

National Language Support, National Language Support Functions, GetLocaleInfoEx, GetSystemDefaultLCID, GetUserDefaultLCID, SetLocaleInfo, MAKELCID

Community Content   What is Community Content?
Add new content RSS  Annotations
LOCALE_NOUSEROVERRIDE should be avoided      Shawn Steele - MSFT   |   Edit   |  

LOCALE_NOUSEROVERRIDE should be avoided

Users specify overrides for a reason :), and expect them to be used. If your app needs a specific format, it should pass in a format instead of depending on the locale data. (See "Culture data shouldn't be considered stable (except for Invariant)" http://blogs.msdn.com/shawnste/archive/2005/04/05/405694.aspx

Tags What's this?: Add a tag
Flag as ContentBug
GetLocaleInfoEx is preferred      Shawn Steele - MSFT   |   Edit   |  

GetLocaleInfoEx is preferred

Try to avoid LCIDs and use locale names if possible

Users can create custom locales which your application may not have access to if it doesn't use the locale name. Custom locales don't get their own LCIDs, so functionality is limited if your application relies on the LCID. See this blog http://blogs.msdn.com/shawnste/pages/custom-cultures-vista-custom-locales.aspx for more info about locales/custom locales and good behavior with locales.

Tags What's this?: Add a tag
Flag as ContentBug
GetLocalInfoEx is Vista and later only...      Red!   |   Edit   |  

I wanted to use GetLocaleInfoEx... until I realized It's Vista+ only... I would use it if the app was only used on that target system but for simplicitie's sake I won't code a wrapper nor compile a special runtime just to support Ex on Vista...

Tags What's this?: Add a tag
Flag as ContentBug
Sample usage of GetLocaleInfo()      ddaS-edEn   |   Edit   |  

This snippet will get the English name of the current user's default language:

LCID lcidLocaleId;     // locale identifier
LCTYPE lctyLocaleInfo; // information type
PWSTR pstr;            // information buffer
INT iBuffSize;         // size of buffer
lcidLocaleId = LOCALE_USER_DEFAULT;
lctyLocaleInfo = LOCALE_SENGLANGUAGE /*0x00001001*/;
// Determine the size of the buffer needed to retrieve information.
iBuffSize = GetLocaleInfo( lcidLocaleId, lctyLocaleInfo, NULL, 0 );
if(iBuffSize > 0)
{
    // Allocate the buffer for the locale info string
    pstr = (WCHAR *) malloc( iBuffSize * sizeof(WCHAR) );
    if(pstr != NULL)
    {
        if(GetLocaleInfoW( lcidLocaleId, lctyLocaleInfo, pstr, iBuffSize ))
        {
            MessageBox(pstr);
        }
        free(pstr); //free locale info string
    }
}

CALID - Calendar ID is DWORD      ddaS-edEn ... Shawn Steele - MSFT   |   Edit   |  

With reference to CALID used in the code fragment in this article as such:

int ret;
DWORD value
CALID calid;
ret = GetLocaleInfoW( LOCALE_USER_DEFAULT,
                     LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                     (LPWSTR)&value;,
                     sizeof(value) / sizeof(WCHAR) );
calid = value;

Note that LOCALE_RETURN_NUMBER is expecting a DWORD to be returned, so strictly you probably shouldn't pass in a CALID, except it happens to be a DWORD so it works.

The length that GetLocaleInfo() expects is in terms of the string, so sizeof(TCHAR) is correct, although I'd prefer use of the W version and WCHAR explicitly.


CALID is defined in WinNls.h as such:

//
//  Calendar ID.
//
typedef DWORD CALID;

© 2008 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker