Expand Minimize

IsNLSDefinedString function

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

Syntax


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

Parameters

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.

Remarks

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.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Winnls.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

National Language Support
National Language Support Functions
CompareString
GetNLSVersion
LCMapString
NLSVERSIONINFO
SYSNLS_FUNCTION

 

 

Community Additions

ADD
Show:
© 2014 Microsoft