Export (0) Print
Expand All
Expand Minimize

GetNLSVersionEx function

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_opt_  LPCWSTR lpLocaleName,
  _Inout_   LPNLSVERSIONINFOEX lpVersionInformation
);

Parameters

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

  1. Use GetNLSVersionEx to retrieve an NLSVERSIONINFOEX structure when doing the original indexing of your data.
  2. 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.
  3. When using the index use GetNLSVersionEx to discover the version of your data.
  4. 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.
  5. 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

Minimum supported client

Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 [desktop apps | Windows Store apps]

Header

Winnls.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

National Language Support
National Language Support Functions
Handling Sorting in Your Applications
GetNLSVersion
NLSVERSIONINFO
NLSVERSIONINFOEX
SYSNLS_FUNCTION
How to tell if the collation version changed

 

 

Community Additions

ADD
Show:
© 2014 Microsoft