Retrieves information about the current version of a specified NLS capability for a locale specified by name.
Note The application should call this function in preference to GetNLSVersion if designed to run only on Windows Vista and later.
BOOL GetNLSVersionEx( _In_ NLS_FUNCTION function, _In_opt_ LPCWSTR lpLocaleName, _Inout_ LPNLSVERSIONINFOEX lpVersionInformation );
- function [in]
The NLS capability to query. This value must be COMPARE_STRING. See the SYSNLS_FUNCTION enumeration.
- lpLocaleName [in, optional]
Pointer to a locale name, or one of the following predefined values.
- lpVersionInformation [in, out]
Pointer to an NLSVERSIONINFOEX structure. The application must initialize the dwNLSVersionInfoSize member to
Note On Windows Vista and later, the function can alternatively provide version information in an NLSVERSIONINFO structure.
Returns TRUE if and only if the application has supplied valid values in lpVersionInformation, or FALSE otherwise. To get extended error information, the application can call GetLastError, which can return one of the following error codes:
- ERROR_INSUFFICIENT_BUFFER. A supplied buffer size was not large enough, or it was incorrectly set to NULL.
- ERROR_INVALID_FLAGS. The values supplied for flags were not valid.
- ERROR_INVALID_PARAMETER. Any of the parameter values was invalid.
This function allows an application such as Active Directory to determine if an NLS change affects the locale used for a particular index table. If it does not, there is no need to re-index the table. For more information, see Handling Sorting in Your Applications. In particular, to tell if a sort version changed and you need to reindex:
- Use GetNLSVersionEx to retrieve an NLSVERSIONINFOEX structure when doing the original indexing of your data.
- Store the following properties with your index to identify the version:
- NLSVERSIONINFOEX.dwNLSVersion. This specifies the version of the sorting table you're using.
- NLSVERSIONINFOEX.dwEffectiveId. This specifies the effective locale of your sort. A custom locale will point to an in-box locale's sort.
- NLSVERSIONINFOEX.guidCustomVersion. This is a GUID specifying a specific custom sort for custom locales that have them.
- When using the index use GetNLSVersionEx to discover the version of your data.
- If any of the three properties has changed, the sorting data you're using could return different results and any indexing you have may fail to find records.
- If you know that your data doesn't contain invalid Unicode code points (that is, all of your strings passed a call to IsNLSDefinedString) then you may consider them the same if only the low byte of dwNLSVersion changed (the minor version described above).
This is covered in more detail in the blog entry "How to tell if the collation version changed" (http://blogs.msdn.com/shawnste/archive/2007/06/01/how-to-tell-if-the-collation-version-changed.aspx).
This function supports custom locales. If lpLocaleName specifies a supplemental locale, the data retrieved is the correct data for the sort order associated with that supplemental locale.
Minimum supported client
|Windows Vista [desktop apps | Windows Store apps]|
Minimum supported server
|Windows Server 2008 [desktop apps | Windows Store apps]|
- National Language Support
- National Language Support Functions
- Handling Sorting in Your Applications
- How to tell if the collation version changed