Maps one Unicode string to another, performing the specified transformation. For an overview of the use of the string functions, see Strings.
Caution Using FoldString incorrectly can compromise the security of your application. Strings that are not mapped 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.
int FoldString( _In_ DWORD dwMapFlags, _In_ LPCTSTR lpSrcStr, _In_ int cchSrc, _Out_opt_ LPTSTR lpDestStr, _In_ int cchDest );
- dwMapFlags [in]
Flags specifying the type of transformation to use during string mapping. This parameter can be a combination of the following values.
- lpSrcStr [in]
Pointer to a source string that the function maps.
- cchSrc [in]
Size, in characters, of the source string indicated by lpSrcStr, excluding the terminating null character. The application can set the parameter to any negative value to specify that the source string is null-terminated. In this case, the function calculates the string length automatically, and null-terminates the mapped string indicated by lpDestStr.
- lpDestStr [out, optional]
Pointer to a buffer in which this function retrieves the mapped string.
- cchDest [in]
Size, in characters, of the destination string indicated by lpDestStr. If space for a terminating null character is included in cchSrc, cchDest must also include space for a terminating null character.
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. If the MAP_FOLDDIGITS flag is specified, the return value is the maximum size required, even if the actual number of characters needed is smaller than the maximum size. If the maximum size is not passed, the function fails with ERROR_INSUFFICIENT_BUFFER.
Returns the number of characters in the translated string, 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, including a terminating null character.
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_DATA. The data was invalid.
- ERROR_INVALID_FLAGS. The values supplied for flags were not valid.
- ERROR_INVALID_PARAMETER. Any of the parameter values was invalid.
- ERROR_MOD_NOT_FOUND. The module was not found.
- ERROR_OUTOFMEMORY. Not enough storage was available to complete this operation.
- ERROR_PROC_NOT_FOUND. The required procedure was not found.
The values of the lpSrcStr and and lpDestStr parameters must not be the same. If they are the same, the function fails with ERROR_INVALID_PARAMETER.
The compatibility zone in Unicode consists of characters in the range 0xF900 through 0xFFEF that are assigned to characters from other encoding standards for characters but are actually variants of characters already in Unicode. The compatibility zone is used to support round-trip mapping to these standards. Applications can use the MAP_FOLDCZONE flag to avoid supporting the duplication of characters in the compatibility zone.
Startng with Windows Vista: This function supports Unicode normalization. All Unicode compatibility characters are mapped.
Startng with Windows Vista: The transformations indicated by the MAP_FOLDCZONE, MAP_PRECOMPOSED, and MAP_COMPOSITE flags use Unicode normalization forms KC, C, and D (through the NormalizeString function) to do the mappings.
Starting with Windows 8: The ANSI version of the function is declared in Winnls.h and the Unicode version is declared in Stringapiset.h. Before Windows 8, both versions were declared in Winnls.h.
Minimum supported client
|Windows 2000 Professional [desktop apps only]|
Minimum supported server
|Windows 2000 Server [desktop apps only]|
Unicode and ANSI names
|FoldStringW (Unicode) and FoldStringA (ANSI)|
- National Language Support
- National Language Support Functions
- Using Unicode Normalization to Represent Strings
- Security Considerations: International Features