LCMapStringEx function
For a locale specified by name, maps an input character string to another using a specified transformation, or generates a sort key for the input string.
Syntax
int LCMapStringEx( _In_opt_ LPCWSTR lpLocaleName, _In_ DWORD dwMapFlags, _In_ LPCWSTR lpSrcStr, _In_ int cchSrc, _Out_opt_ LPWSTR lpDestStr, _In_ int cchDest, _In_opt_ LPNLSVERSIONINFO lpVersionInformation, _In_opt_ LPVOID lpReserved, _In_opt_ LPARAM sortHandle );
Parameters
- lpLocaleName [in, optional]
-
Pointer to a locale name, or one of the following predefined values.
- dwMapFlags [in]
-
Flag specifying the type of transformation to use during string mapping or the type of sort key to generate. This parameter can have the following values.
The following flags can be used alone, with one another, or with the LCMAP_SORTKEY and/or LCMAP_BYTEREV flags. However, they cannot be combined with the other flags listed above.
The flags listed below are used only with the LCMAP_SORTKEY flag.
- lpSrcStr [in]
-
Pointer to a source string that the function maps or uses for sort key generation. This string cannot have a size of 0.
- cchSrc [in]
-
Size, in characters, of the source string indicated by lpSrcStr. The size of the source string can include the terminating null character, but does not have to. If the terminating null character is included, the mapping behavior of the function is not greatly affected because the terminating null character is considered to be unsortable and always maps to itself.
The application can set this parameter to any negative value to specify that the source string is null-terminated. In this case, if LCMapStringEx is being used in its string-mapping mode, the function calculates the string length itself, and null-terminates the mapped string indicated by lpDestStr.
The application cannot set this parameter to 0.
- lpDestStr [out, optional]
-
Pointer to a buffer in which this function retrieves the mapped string or sort key. If the application specifies LCMAP_SORTKEY, the function stores a sort key in the buffer as an opaque array of byte values that can include embedded 0 bytes.
Note If the function fails, the destination buffer might contain either partial results or no results at all. In this case, it is recommended for your application to consider any results invalid. - cchDest [in]
-
Size, in characters, of the buffer indicated by lpDestStr. If the application is using the function for string mapping, it supplies a character count for this parameter. If space for a terminating null character is included in cchSrc, cchDest must also include space for a terminating null character.
If the application is using the function to generate a sort key, it supplies a byte count for the size. This byte count must include space for the sort key 0x00 terminator.
The application can set cchDest to 0. In this case, the function does not use the lpDestStr parameter and returns the required buffer size for the mapped string or sort key.
- lpVersionInformation [in, optional]
-
Pointer to an NLSVERSIONINFOEX structure that contains the version information about the relevant NLS capability; usually retrieved from GetNLSVersionEx.
Windows Vista, Windows 7: Reserved; must set to NULL.
- lpReserved [in, optional]
-
Reserved; must be NULL.
- sortHandle [in, optional]
-
Reserved; must be 0.
Return value
Returns the number of characters or bytes in the translated string or sort key, including a terminating null character, if successful. If the function succeeds and the value of cchDest is 0, the return value is the size of the buffer required to hold the translated string or sort key, including a terminating null character if the input was null terminated.
This function returns 0 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_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
The application can use LCMapString or LCMapStringEx to generate a sort key. To do this, the application specifies LCMAP_SORTKEY for the dwMapFlags parameter. For more information, see Handling Sorting in Your Applications.
Another way for your application to use LCMapString or LCMapStringEx is in mapping strings. In this case, the application does not specify LCMAP_SORTKEY for the dwMapFlags parameter, but supplies some other combination of flags. For more information, see Handling Sorting in Your Applications.
Beginning in Windows Vista: This function can handle data from custom locales. Data is not guaranteed to be the same from computer to computer or between runs of an application. If your application must persist or transmit data, see Using Persistent Locale Data.
Beginning in Windows 8: If your app passes language tags to this function from the Windows.Globalization namespace, it must first convert the tags by calling ResolveLocaleName.
Requirements
|
Minimum supported client |
Windows Vista [desktop apps | Windows Store apps] |
|---|---|
|
Minimum supported server |
Windows Server 2008 [desktop apps | Windows Store apps] |
|
Minimum supported phone |
Windows Phone 8.1 |
|
Header |
|
|
Library |
|
|
DLL |
|
See also
- National Language Support
- National Language Support Functions
- Handling Sorting in Your Applications
- CompareString
- FindNLSStringEx
- GetNLSVersionEx
- LCMapString