Функция GetLocaleInfoEx (winnls.h)

Статья
08/27/2023

Извлекает сведения о языковом стандарте, указанном по имени.

Примечание Приложение должно вызывать эту функцию в предпочтительном варианте GetLocaleInfo , если оно предназначено для работы только в Windows Vista и более поздних версиях.

Примечание Эта функция может извлекать данные, которые изменяются между выпусками, например из-за пользовательского языкового стандарта. Если приложение должно сохранять или передавать данные, см. статью Использование данных сохраняемого языкового стандарта.

Синтаксис

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

Параметры

[in, optional] lpLocaleName

Указатель на имя языкового стандарта или одно из следующих предопределенных значений.

[in] LCType

Извлекаемая информация о языковом стандарте. Возможные значения см. в разделе "Константы, используемые в параметре LCType для GetLocaleInfo, GetLocaleInfoEx и SetLocaleInfo" статьи Константы сведений о языковом стандарте. Обратите внимание, что для каждого вызова можно указать только один фрагмент сведений о языковом стандарте.

Приложение может использовать бинарный оператор OR для объединения LOCALE_RETURN_NUMBER с любой другой разрешенной константой. В этом случае функция извлекает значение в виде числа, а не строки. Буфер, получающий значение, должен быть не ниже длины значения DWORD, т. е. 2.

Осторожностью Также можно объединить LOCALE_NOUSEROVERRIDE с любой другой константой. Однако использование этой константы настоятельно не рекомендуется. (Даже без переопределения текущего пользователя данные могут отличаться от компьютера к компьютеру, а пользовательские языковые стандарты могут изменять данные. Например, даже названия месяцев или дней подлежат орфографическим реформам.)

Если LCType имеет значение LOCALE_IOPTIONALCALENDAR, функция извлекает только первый альтернативный календарь.

Примечание Чтобы получить все альтернативные календари, приложение должно использовать EnumCalendarInfoEx.

Начиная с Windows Vista, приложения не должны использовать LOCALE_ILANGUAGE в параметре LCType , чтобы избежать сбоя или получения непредвиденных данных. Вместо этого приложениям рекомендуется вызывать GetLocaleInfoEx.

[out, optional] lpLCData

Указатель на буфер, в котором эта функция извлекает запрошенные сведения о языковом стандарте. Этот указатель не используется, если параметр cchData имеет значение 0.

[in] cchData

Размер буфера данных в символах, указанный lpLCData. Кроме того, приложение может задать для этого параметра значение 0. В этом случае функция не использует параметр lpLCData и возвращает требуемый размер буфера, включая завершающий символ NULL.

Возвращаемое значение

Возвращает количество символов, полученных в буфере данных языкового стандарта, если это успешно, а cchData имеет ненулевое значение. Если функция выполнена успешно, параметр cchData не имеет нулевого значения и указан LOCALE_RETURN_NUMBER , то возвращаемое значение — это размер целого числа, полученного в буфере данных, т. е. 2. Если функция выполняется успешно и значение cchData равно 0, возвращаемое значение является требуемым размером в символах, включая пустой символ, для буфера данных языкового стандарта.

Функция возвращает значение 0, если не удалось. Чтобы получить расширенные сведения об ошибке, приложение может вызвать Метод GetLastError, который может возвращать один из следующих кодов ошибок:

ERROR_INSUFFICIENT_BUFFER. Указанный размер буфера был недостаточно велик или для него неправильно задано значение NULL.
ERROR_INVALID_FLAGS. Значения, указанные для флагов, были недопустимыми.
ERROR_INVALID_PARAMETER. Любое из значений параметров было недопустимым.

Эта функция обычно извлекает сведения в текстовом формате. Если сведения являются числовым значением и значением LCTypeявляется LOCALE_ILANGUAGE или LOCALE_IDEFAULTLANGUAGE, эта функция извлекает строки, содержащие шестнадцатеричные числа. В противном случае полученный текст для числовых сведений является десятичным числом.

Существует два исключения из этого правила. Во-первых, приложение может получать числовые значения в виде целых чисел, указывая LOCALE_RETURN_NUMBER в параметре LCType . Второе исключение заключается в том, что LOCALE_FONTSIGNATURE ведет себя иначе, чем все остальные константы сведений о языковом стандарте. Приложение должно предоставить буфер данных размером не менее байтов sizeof(LOCALESIGNATURE). При успешном возвращении из функции буфер заполняется в виде структуры LOCALESIGNATURE .

Примечание Даже если параметр LCType указан как LOCALE_FONTSIGNATURE, cchData и возвращаемая функция по-прежнему являются числом символов. Когда приложение вызывает GetLocaleInfoEx с LCType , указанным как LOCALE_FONTSIGNATURE, cchData можно безопасно указать как sizeof(LOCALESIGNATURE) / sizeof(WCHAR).

В следующих примерах правильно описывается размер буфера для нетекстовых значений:

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

Эта функция может извлекать данные из пользовательских языковых стандартов. Данные не обязательно будут одинаковыми с компьютера на компьютер или между запусками приложения. Если приложение должно сохранять или передавать данные, см. статью Использование данных сохраняемого языкового стандарта.

Начиная с Windows 8. Если приложение передает языковые теги в эту функцию из пространства имен Windows.Globalization, оно должно сначала преобразовать теги, вызвав ResolveLocaleName.

Примеры

Примеры использования этой функции можно найти в примерах NLS: ПРИМЕР API на основе имен и Пример устранения рисков С помощью международного доменного имени (IDN).

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winnls.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll