getLocaleInfoW 函式 (winnls.h)

發行項
03/13/2024

擷取標識碼所指定地區設定的相關信息。

注意基於互操作性考慮，應用程式應該偏好 GetLocaleInfoEx 函式至 GetLocaleInfo ，因為 Microsoft 正移轉至使用地區設定名稱，而不是新地區設定的地區設定標識符。只有在 Windows Vista 和更新版本上執行的任何應用程式都應該使用 GetLocaleInfoEx。

語法

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

參數

[in] Locale

要擷取資訊的地區設定標識碼。您可以使用 MAKELCID 宏來建立地區設定標識碼，或使用下列其中一個預先定義的值。

[in] LCType

要擷取的地區設定資訊。如需詳細定義，請參閱 GetLocaleInfoEx 的 LCType 參數。

注意針對 GetLocaleInfo，值LOCALE_USE_CP_ACP僅與 ANSI 版本相關。

[out, optional] lpLCData

此函式擷取所要求地區設定資訊的緩衝區指標。如果 cchData 設定為 0，則不會使用此指標。如需詳細資訊，請參閱＜備註＞一節。

[in] cchData

大小，以 TCHAR 為單位，以 lpLCData 表示的數據緩衝區。或者，應用程式可以將此參數設定為 0。在此情況下，函式不會使用 lpLCData 參數，並傳回必要的緩衝區大小，包括終止的 Null 字元。

傳回值

如果成功且 cchData 為非零值，則會傳回在地區設定數據緩衝區中擷取的字元數。如果函式成功， cchData 為非零，而且指定LOCALE_RETURN_NUMBER ，則傳回值會是數據緩衝區中擷取的整數大小;也就是說，2 表示函式的 Unicode 版本，或 ANSI 版本的 4。如果函式成功且 cchData 的值為 0，則傳回值會是地區設定數據緩衝區的必要大小，以包含 Null 字元的字元為單位。

如果函式不成功，函式會傳回 0。若要取得擴充的錯誤資訊，應用程式可以呼叫 GetLastError，這可以傳回下列其中一個錯誤碼：

ERROR_INSUFFICIENT_BUFFER。提供的緩衝區大小不夠大，或設定為 NULL 不正確。
ERROR_INVALID_FLAGS。為旗標的值無效。
ERROR_INVALID_PARAMETER。任何參數值都無效。

備註

如需此函式的作業，請參閱 GetLocaleInfoEx 的備註。

注意即使 將 LCType 參數指定為 LOCALE_FONTSIGNATURE，cchData 和函式傳回仍為 TCHAR 計數。 ANSI 和 Unicode 版本的函式計數不同。當應用程式使用 LOCALE_FONTSIGNATURE 呼叫 GetLocaleInfo 的一般版本時， 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 代碼頁，從 Unicode 轉譯為 ANSI。不過，如果指定 LOCALE_USE_CP_ACP ，翻譯會以系統預設 ANSI 代碼頁為基礎。

當此函式的 ANSI 版本與僅限 Unicode 的地區設定識別碼搭配使用時，函式可能會成功，因為操作系統使用系統代碼頁。不過，系統代碼頁中未定義的字元會顯示在字串中，做為問號 (？) 。

注意

winnls.h 標頭會將 GetLocaleInfo 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows 2000 Server [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	winnls.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll