getLocaleInfoEx 函数 (winnls.h)

项目
03/13/2024

检索有关由名称指定的区域设置的信息。

注意如果设计为仅在 Windows Vista 及更高版本上运行，则应用程序应优先调用 GetLocaleInfo 。

注意此函数可以检索版本之间发生更改的数据，例如，由于自定义区域设置。如果应用程序必须保留或传输数据，请参阅使用持久区域设置数据。

语法

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

参数

[in, optional] lpLocaleName

指向区域设置名称或以下预定义值之一的指针。

[in] LCType

要检索的区域设置信息。有关可能的值，请参阅区域设置信息常量中的“GetLocaleInfo、GetLocaleInfoEx 和 SetLocaleInfo 的 LCType 参数中使用的常量”部分。请注意，每个调用只能指定一条区域设置信息。

应用程序可以使用二进制 OR 运算符将 LOCALE_RETURN_NUMBER 与任何其他允许的常量组合在一起。在这种情况下，函数以数字而不是字符串的形式检索值。接收值的缓冲区必须至少为 DWORD 值的长度，即 2。

谨慎还可以将 LOCALE_NOUSEROVERRIDE 与任何其他常量组合在一起。但是，强烈建议不要使用此常量。 (即使不使用当前用户替代，数据也会因计算机而异，并且自定义区域设置可以更改数据。例如，即使月份或日期的名称也会受到拼写改革的约束。)

如果 LCType 设置为 LOCALE_IOPTIONALCALENDAR，则函数仅检索第一个备用日历。

注意若要获取所有备用日历，应用程序应使用 EnumCalendarInfoEx。

从 Windows Vista 开始，应用程序不应使用 LCType 参数中的LOCALE_ILANGUAGE，以避免失败或检索意外数据。相反，建议应用程序调用 GetLocaleInfoEx。

[out, optional] lpLCData

指向缓冲区的指针，此函数在其中检索请求的区域设置信息。如果 cchData 设置为 0，则不使用此指针。

[in] cchData

lpLCData 指示的数据缓冲区的大小（以字符为单位）。或者，应用程序可以将此参数设置为 0。在这种情况下，函数不使用 lpLCData 参数，并返回所需的缓冲区大小，包括终止 null 字符。

返回值

如果成功且 cchData 为非零值，则返回在区域设置数据缓冲区中检索到的字符数。如果函数成功， 则 cchData 为非零值，并且指定LOCALE_RETURN_NUMBER ，则返回值是数据缓冲区中检索到的整数的大小，即 2。如果函数成功且 cchData 的值为 0，则返回值是区域设置数据缓冲区所需的大小（以字符为单位，包括 null 字符）。

如果函数不成功，则返回 0。若要获取扩展的错误信息，应用程序可以调用 GetLastError，这会返回以下错误代码之一：

ERROR_INSUFFICIENT_BUFFER。提供的缓冲区大小不够大，或者错误地设置为 NULL。
ERROR_INVALID_FLAGS。为标志提供的值无效。
ERROR_INVALID_PARAMETER。任何参数值都无效。

注解

此函数通常检索文本格式的信息。如果信息是数值，并且 LCType 的值 LOCALE_ILANGUAGE 或 LOCALE_IDEFAULTLANGUAGE，则此函数将检索包含十六进制数的字符串。否则，检索到的数字信息文本是十进制数。

以下为此规则的两种例外情况。首先，应用程序可以通过在 LCType 参数中指定LOCALE_RETURN_NUMBER来以整数的形式检索数值。第二个例外是，LOCALE_FONTSIGNATURE 的行为方式不同于所有其他区域设置信息常量。应用程序必须提供大小至少为 (LOCALESIGNATURE) 字节的数据缓冲区。从函数成功返回后，缓冲区将填充为 LOCALESIGNATURE 结构。

注意即使 将 LCType 参数指定为 LOCALE_FONTSIGNATURE，cchData 和函数返回仍然是字符计数。当应用程序使用 LCType 指定为 LOCALE_FONTSIGNATURE 调用 GetLocaleInfoEx 时，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 示例和 NLS：国际化域名 (IDN) 缓解示例中找到显示此函数用法的示例。

要求

要求	值
最低受支持的客户端	Windows Vista [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2008 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	winnls.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll