IsNLSDefinedString function (winnls.h)
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 );
NLS capability to query. This value must be COMPARE_STRING. See the SYSNLS_FUNCTION enumeration.
Flags defining the function. Must be 0.
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.
Pointer to the UTF-16 string to examine.
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.
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]|
|Header||winnls.h (include Windows.h)|