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

Статья
11/20/2024

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

Примечание По соображениям взаимодействия приложение должно предпоч есть функцию 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, возвращаемое значение является обязательным размером в символах, включая пустой символ, для буфера данных языкового стандарта.

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

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

Замечания

Сведения об операции этой функции см. в примечаниях для GetLocaleInfoEx.

Примечание Даже если параметр 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]
целевая платформа	Виндоус
заголовка	winnls.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll