Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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, optional] LPINT pcchFound
);
Parameters
[in] Locale
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.[in] dwFindNLSStringFlags
Flags specifying details of the find operation. For detailed definitions, see the dwFindNLSStringFlags parameter of FindNLSStringEx.
[in] lpStringSource
Pointer to the source string, in which the function searches for the string specified by lpStringValue.
[in] cchSource
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.
[in] lpStringValue
Pointer to the search string, for which the function searches in the source string.
[in] cchValue
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.
[out, optional] pcchFound
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
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | winnls.h (include Windows.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |
See also
Handling Sorting in Your Applications