GetNLSVersionEx function (winnls.h)

Article
02/22/2024

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.

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).

Note On Windows Vista and later, the function can alternatively provide version information in an NLSVERSIONINFO structure.

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 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.

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