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

Статья
08/27/2023

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

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

Примечание Для обеспечения глобальной совместимости приложение должно предпочесть формы API "W" Юникода формам "A". GetLocaleInfoA ограничит число символьных данных и может привести к повреждаемого результата для пользователей, особенно в приложениях с глобальной поддержкой. Для этого API предпочтительным является GetLocaleInfoEx , так как это Юникод, а также поддерживает современные стандарты имен языковых стандартов.

Синтаксис

int GetLocaleInfoA(
  [in]            LCID   Locale,
  [in]            LCTYPE LCType,
  [out, optional] LPSTR  lpLCData,
  [in]            int    cchData
);

Параметры

[in] Locale

Идентификатор языкового стандарта , для которого требуется получить сведения. Вы можете использовать макрос MAKELCID для создания идентификатора языкового стандарта или использовать одно из следующих предопределенных значений.

[in] LCType

Извлекаемая информация о языковом стандарте. Подробные определения см. в параметре LCTypeобъекта GetLocaleInfoEx.

Примечание Для GetLocaleInfo значение LOCALE_USE_CP_ACP относится только к версии ANSI.

[out, optional] lpLCData

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

[in] cchData

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

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

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

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

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

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

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

int   ret;
CALID calid;
DWORD value;

ret = GetLocaleInfo(LOCALE_USER_DEFAULT,
                    LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                    (LPTSTR)&value,
                    sizeof(value) / sizeof(TCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

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

Строка ANSI, полученная версией ANSI этой функции, преобразуется из Юникода в ANSI на основе кодовой страницы ANSI по умолчанию для идентификатора языкового стандарта. Однако если указано LOCALE_USE_CP_ACP , перевод основан на системной кодовой странице ANSI по умолчанию.

Если версия ANSI этой функции используется с идентификатором языкового стандарта только в Юникоде, функция может завершиться успешно, так как операционная система использует системную кодовую страницу. Однако символы, которые не определены на системной кодовой странице, отображаются в строке как вопросительный знак (?).

Примечание

Заголовок winnls.h определяет GetLocaleInfo как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


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