CompareStringWrapW function

[CompareStringWrapW is available for use in Windows XP. It will not be available in subsequent versions. You should use CompareStringW in its place.]

Compares two Unicode character strings, using a specified locale.

Note

CompareStringWrapW is a wrapper for the CompareStringW function. See the CompareString page for further usage notes.

 

Syntax

int CompareStringWrapW(
  _In_ LCID    Locale,
  _In_ DWORD   dwCmpFlags,
  _In_ LPCWSTR lpString1,
  _In_ int     cchCount1,
  _In_ LPCWSTR lpString2,
  _In_ int     cchCount2
);

Parameters

Locale [in]

Type: LCID

A locale identifier used for the comparison. This parameter can be one of the following predefined locale identifiers or a locale identifier created by the MAKELCID macro.

LOCALE_SYSTEM_DEFAULT

The system's default locale.

LOCALE_USER_DEFAULT

The current user's default locale.

dwCmpFlags [in]

Type: DWORD

The flags that indicate how the function compares the two strings. By default, these flags are not set. Set to zero to get the default behavior or to any combination of the following values.

NORM_IGNORECASE

Ignore case.

NORM_IGNOREKANATYPE

Do not differentiate between Hiragana and Katakana characters. Corresponding Hiragana and Katakana characters compare as equal.

NORM_IGNORENONSPACE

Ignore nonspacing characters.

NORM_IGNORESYMBOLS

Ignore symbols.

NORM_IGNOREWIDTH

Do not differentiate between a single-byte character and the same character as a double-byte character.

SORT_STRINGSORT

Treat punctuation the same as symbols.

lpString1 [in]

Type: LPCWSTR

A pointer to the first Unicode string to be compared.

cchCount1 [in]

Type: int

The number of characters in the string pointed to by the lpString1 parameter. The count does not include the terminating null character. If this parameter is a negative value, the string is assumed to be null-terminated and the length is calculated automatically.

lpString2 [in]

Type: LPCWSTR

A pointer to the second Unicode string to be compared.

cchCount2 [in]

Type: int

The number of characters in the string pointed to by the lpString2 parameter. The count does not include the terminating null character. If this parameter is a negative value, the string is assumed to be null-terminated and the length is calculated automatically.

Return value

Type: int

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes.

  • ERROR_INVALID_FLAGS
  • ERROR_INVALID_PARAMETER

If the function succeeds, the return value is one of the following values.

Requirement Value
CSTR_LESS_THAN The string pointed to by the lpString1 parameter is less in lexical value than the string pointed to by the lpString2 parameter.
CSTR_EQUAL The string pointed to by lpString1 is equal in lexical value to the string pointed to by lpString2.
CSTR_GREATER_THAN The string pointed to by lpString1 is greater in lexical value than the string pointed to by lpString2

 

Remarks

Security Warning: Using this function incorrectly can compromise the security of your application. Strings that are not compared correctly can produce invalid input. Test strings to make sure they are valid before using them and provide error handlers. For more information, see Security Considerations: International Features

The preferred method is to use CompareStringW in conjunction with the Microsoft Layer for Unicode (MSLU).

CompareStringWrapW must be called directly from Shlwapi.dll, using ordinal 45.

Requirements

Requirement Value
Minimum supported client
Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server
Windows Server 2003 [desktop apps only]
Header
None
DLL
Shlwapi.dll (version 5.0 or later)

See also

CompareString