Expand Minimize

FindNLSString function

Locates a Unicode string (wide characters) or its equivalent in another Unicode string for a locale specified by identifier.

Caution  Because strings with very different binary representations can compare as identical, this function can raise certain security concerns. For more information, see the discussion of comparison functions in Security Considerations: International Features.

Note  For interoperability reasons, the application should prefer the FindNLSStringEx function because Microsoft is migrating toward the use of locale names instead of locale identifiers for new locales. Although FindNLSString supports custom locales, most applications should use FindNLSStringEx for this type of support.

Syntax


int FindNLSString(
  _In_       LCID Locale,
  _In_       DWORD dwFindNLSStringFlags,
  _In_       LPCWSTR lpStringSource,
  _In_       int cchSource,
  _In_       LPCWSTR lpStringValue,
  _In_       int cchValue,
  _Out_opt_  LPINT pcchFound
);

Parameters

Locale [in]

Locale identifier that specifies the locale. You can use the MAKELCID macro to create an identifier or use one of the following predefined values.

Windows Vista and later: The following custom locale identifiers are also supported.

dwFindNLSStringFlags [in]

Flags specifying details of the find operation. For detailed definitions, see the dwFindNLSStringFlags parameter of FindNLSStringEx.

lpStringSource [in]

Pointer to the source string, in which the function searches for the string specified by lpStringValue.

cchSource [in]

Size, in characters excluding the terminating null character, of the string indicated by lpStringSource. The application cannot specify 0 or any negative number other than -1 for this parameter. The application specifies -1 if the source string is null-terminated and the function should calculate the size automatically.

lpStringValue [in]

Pointer to the search string, for which the function searches in the source string.

cchValue [in]

Size, in characters excluding the terminating null character, of the string indicated by lpStringValue. The application cannot specify 0 or any negative number other than -1 for this parameter. The application specifies -1 if the search string is null-terminated and the function should calculate the size automatically.

pcchFound [out, optional]

Pointer to a buffer containing the length of the string that the function finds. For details, see the pcchFound parameter of FindNLSStringEx.

Return value

Returns a 0-based index into the source string indicated by lpStringSource if successful. In combination with the value in pcchFound, this index provides the exact location of the entire found string in the source string. A return value of 0 is an error-free index into the source string, and the matching string is in the source string at offset 0.

The function returns -1 if it does not succeed. To get extended error information, the application can call GetLastError, which can return one of the following error codes:

  • ERROR_INVALID_FLAGS. The values supplied for flags were not valid.
  • ERROR_INVALID_PARAMETER. Any of the parameter values was invalid.
  • ERROR_SUCCESS. The action completed successfully but yielded no results.

Remarks

See Remarks for FindNLSStringEx.

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
Handling Sorting in Your Applications
Security Considerations: International Features
CompareString
FindNLSStringEx
LCMapString

 

 

Community Additions

ADD
Show:
© 2014 Microsoft