DownlevelLCIDToLocaleName function

Article
11/06/2023

Converts a locale identifier to a locale name.

Note

This function is used only by applications that run on pre-Windows Vista operating systems. Its use requires a download package. Applications that run only on Windows Vista and later should call LCIDToLocaleName to retrieve a locale name.

Syntax

int DownlevelLCIDToLocaleName(
  _In_  LCID   Locale,
  _Out_ LPWSTR lpName,
  _In_  int    cchName,
  _In_  DWORD  dwFlags
);

Parameters

Locale [in]

The locale identifier to translate. You can use the MAKELCID macro to create a locale identifier. This function does not support neutral locales or the following specific locale identifier values.

lpName [out]

Pointer to a buffer in which this function retrieves the locale name. The function retrieves NULL if cchName is set to 0.

cchName [in]

Size, in UTF-16 code points, of the locale name buffer. The application sets this parameter to 0 to return the required size of the locale name buffer.

dwFlags [in]

Flags specifying the type of name to retrieve. The default value is DOWNLEVEL_LOCALE_NAME.

Return value

Returns the count of UTF-16 code points in the locale name, including the terminating null character, if successful. If the function succeeds and the value of cchName is 0, the return value is the required size, in characters (including null characters), for the locale name 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 value of dwFlags is not valid.
ERROR_INVALID_PARAMETER. Any of the parameter values were invalid.

Remarks

Note

This function does not support custom locales.

The required header file and DLL are part of the "Microsoft NLS Downlevel Data Mapping APIs" download, which is no longer available from the Microsoft Download Center. Use ICU globalization APIs on Windows 10 May 2019 Update and later versions.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Redistributable	Microsoft NLS Downlevel Data Mapping APIs onWindows XP with SP2 and laterorWindows Vista
Header	Nlsdl.h
DLL	NlsMap.dll