GetNLSVersionEx function (winnls.h)
Retrieves information about the current version of a specified NLS capability for a locale specified by name.
Syntax
BOOL GetNLSVersionEx(
[in] NLS_FUNCTION function,
[in, optional] LPCWSTR lpLocaleName,
[in, out] LPNLSVERSIONINFOEX lpVersionInformation
);
Parameters
[in] function
The NLS capability to query. This value must be COMPARE_STRING. See the SYSNLS_FUNCTION enumeration.
[in, optional] lpLocaleName
Pointer to a locale name, or one of the following predefined values.
[in, out] lpVersionInformation
Pointer to an NLSVERSIONINFOEX structure. The application must initialize the dwNLSVersionInfoSize member to sizeof(NLSVERSIONINFOEX)
.
Return value
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.
Remarks
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 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.
Beginning in Windows 8: If your app passes language tags to this function from the Windows.Globalization namespace, it must first convert the tags by calling ResolveLocaleName.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows Vista [desktop apps | UWP apps] |
Minimum supported server | Windows Server 2008 [desktop apps | UWP apps] |
Target Platform | Windows |
Header | winnls.h (include Windows.h) |
Library | Kernel32.lib |
DLL | Kernel32.dll |
See also
Handling Sorting in Your Applications
How to tell if the collation version changed