GetNLSVersionEx 函式 (winnls.h)

發行項
03/13/2024

擷取名稱所指定地區設定之目前版本的 NLS 功能相關信息。

注意如果設計為只在 Windows Vista 和更新版本上執行，應用程式應該以喜好設定呼叫此函式。

語法

BOOL GetNLSVersionEx(
  [in]           NLS_FUNCTION       function,
  [in, optional] LPCWSTR            lpLocaleName,
  [in, out]      LPNLSVERSIONINFOEX lpVersionInformation
);

參數

[in] function

要查詢的 NLS 功能。此值必須COMPARE_STRING。請參閱 SYSNLS_FUNCTION 列舉。

[in, optional] lpLocaleName

地區設定名稱的指標，或下列其中一個預先定義的值。

[in, out] lpVersionInformation

NLSVERSIONINFOEX 結構的指標。應用程式必須將 dwNLSVersionInfoSize 成員初始化為 sizeof(NLSVERSIONINFOEX)。

注意在 Windows Vista 和更新版本上，函式也可以提供 NLSVERSIONINFO 結構中的版本資訊。

傳回值

只有在應用程式已在 lpVersionInformation 中提供有效值時，否則傳回 TRUE，否則傳回 FALSE。若要取得延伸的錯誤資訊，應用程式可以呼叫 GetLastError，這可以傳回下列其中一個錯誤碼：

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

備註

此函式可讓 Active Directory 之類的應用程式判斷 NLS 變更是否會影響用於特定索引數據表的地區設定。如果沒有，就不需要重新編製數據表的索引。如需詳細資訊，請參閱處理應用程式中的排序。特別是，若要判斷排序版本是否已變更，而且您需要重新編製索引：

當您執行數據的原始索引時，使用 GetNLSVersionEx 來 擷取 NLSVERSIONINFOEX 結構。
使用您的索引儲存下列屬性以識別版本：
- NLSVERSIONINFOEX.dwNLSVersion。這會指定您所使用的排序數據表版本。
- NLSVERSIONINFOEX.dwEffectiveId。這會指定排序的有效地區設定。自訂地區設定會指向內建地區設定的排序。
- NLSVERSIONINFOEX.guidCustomVersion。這是 GUID，指定具有它們之自定義地區設定的特定自定義排序。
使用索引時，請使用 GetNLSVersionEx 來探索數據的版本。
如果三個屬性中的任何一個已變更，您正在使用的排序數據可能會傳回不同的結果，而且任何索引編製可能會找不到記錄。
如果您知道數據不包含無效的 Unicode 字碼點 (，則所有字串都會傳遞對 IsNLSDefinedString) 的呼叫，則只有在dwNLSVersion 的低位元組變更 (上述次要版本) ，您可能會將其視為相同。

部落格文章「如何判斷定序版本變更」 (http://blogs.msdn.com/shawnste/archive/2007/06/01/how-to-tell-if-the-collation-version-changed.aspx).

此函式支援自定義地區設定。如果 lpLocaleName 指定補充地區設定，則擷取的數據是與該補充地區設定相關聯的排序順序的正確數據。

從 Windows 8 開始：如果您的 app 從 Windows.Globalization 命名空間將語言標記傳遞至此函式，則必須先呼叫 ResolveLocaleName 來轉換標記。

規格需求

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