Windows apps
Collapse the table of content
Expand the table of content
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

IsNLSDefinedString function

Determines if each character in a string has a defined result for a specified NLS capability.


BOOL IsNLSDefinedString(
  _In_ NLS_FUNCTION     Function,
  _In_ DWORD            dwFlags,
  _In_ LPNLSVERSIONINFO lpVersionInformation,
  _In_ LPCWSTR          lpString,
  _In_ INT              cchStr


Function [in]

NLS capability to query. This value must be COMPARE_STRING. See the SYSNLS_FUNCTION enumeration.

dwFlags [in]

Flags defining the function. Must be 0.

lpVersionInformation [in]

Pointer to an NLSVERSIONINFO structure containing version information. Typically, the information is obtained by calling GetNLSVersion. The application sets this parameter to NULL if the function is to use the current version.

lpString [in]

Pointer to the UTF-16 string to examine.

cchStr [in]

Number of UTF-16 characters in the string indicated by lpString. This count can include a terminating null character. If the terminating null character is included in the character count, it does not affect the checking behavior because the terminating null character is always defined.

The application should supply -1 to indicate that the string is null-terminated. In this case, the function itself calculates the string length.

Return value

Returns TRUE if successful, only if the input string is valid, 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 differentiates between defined and undefined strings, so that an application such as Active Directory can reject strings with undefined code points. Use of the function can minimize the necessity for the application to re-index its database. For more information, see Handling Sorting in Your Applications.

For example, if Function is set to COMPARE_STRING, IsNLSDefinedString checks for undefined code points, surrogate pairs that represent undefined Unicode characters, or ill-formed surrogate pairs. If the function returns TRUE for a particular string, the results, as retrieved by CompareString or LCMapString with LCMAP_SORTKEY set, are guaranteed to be identical as long as the corresponding NLS version does not change.


Minimum supported client

Windows Vista [desktop apps | UWP apps]

Minimum supported server

Windows Server 2008 [desktop apps | UWP apps]


Winnls.h (include Windows.h)





See also

National Language Support
National Language Support Functions



© 2018 Microsoft