FoldStringA 函数 (winnls.h)

项目
03/13/2024

将一个 Unicode 字符串映射到另一个，执行指定的转换。有关使用字符串函数的概述，请参阅字符串。

谨慎错误地使用 FoldString 可能会危及应用程序的安全性。未正确映射的字符串可能会生成无效的输入。测试字符串，以确保它们在使用前有效，并提供错误处理程序。有关详细信息，请参阅安全注意事项：国际功能。

语法

int FoldStringA(
  [in]            DWORD  dwMapFlags,
  [in]            LPCSTR lpSrcStr,
  [in]            int    cchSrc,
  [out, optional] LPSTR  lpDestStr,
  [in]            int    cchDest
);

参数

[in] dwMapFlags

指定字符串映射期间要使用的转换类型的标志。此参数可以是以下值的组合。

标志	含义
MAP_COMPOSITE	将重音字符映射到分解字符，即基字符和一个或多个非节奏字符各自具有不同的码位值的字符。例如，Ä 由 A + ー：拉丁文大写字母 A (U+0041) + 组合 DIAERESIS (U+0308) 表示。此标志等效于 Windows Vista 中的规范化形式 D。请注意，此标志不能与 MB_PRECOMPOSED 一起使用。
MAP_EXPAND_LIGATURES	展开所有连字字符，使其由两个字符等效项表示。例如，连字“æ” (U+00e6) 扩展为两个字符“a” (U+0061) + “e” (U+0065) 。此值不能与 MAP_PRECOMPOSED 或 MAP_COMPOSITE 组合使用。
MAP_FOLDCZONE	将兼容性区域字符折叠为标准 Unicode 等效项。如果还设置了MAP_COMPOSITE标志，则此标志等效于 Windows Vista 中的规范化形式 KD。如果未 (默认) 设置复合标志，则此标志等效于 Windows Vista 中的规范化形式 KC。
MAP_FOLDDIGITS	将所有数字映射到 Unicode 字符 0 到 9。
MAP_PRECOMPOSED	将重音字符映射到预组合字符，其中重音符和基字符组合成单个字符值。此标志等效于 Windows Vista 中的规范化形式 C。此值不能与 MAP_COMPOSITE 组合使用。

[in] lpSrcStr

指向函数映射的源字符串的指针。

[in] cchSrc

lpSrcStr 指示的源字符串的大小（以字符为单位），不包括终止 null 字符。应用程序可以将参数设置为任何负值，以指定源字符串以 null 结尾。在这种情况下，函数会自动计算字符串长度，并用 null 终止 lpDestStr 指示的映射字符串。

[out, optional] lpDestStr

指向此函数在其中检索映射字符串的缓冲区的指针。

[in] cchDest

lpDestStr 指示的目标字符串的大小（以字符为单位）。如果 cchSrc 中包含终止 null 字符的空间， 则 cchDest 还必须包含终止 null 字符的空间。

应用程序可以将 cchDest 设置为 0。在这种情况下，函数不使用 lpDestStr 参数，并返回映射字符串所需的缓冲区大小。如果指定了MAP_FOLDDIGITS标志，则返回值是所需的最大大小，即使所需的实际字符数小于最大大小也是如此。如果未传递最大大小，函数将失败并ERROR_INSUFFICIENT_BUFFER。

返回值

如果成功，则返回已翻译字符串中的字符数，包括终止 null 字符。如果函数成功且 cchDest 的值为 0，则返回值是保存已转换字符串所需的缓冲区大小，包括终止 null 字符。

如果此函数不成功，则返回 0。若要获取扩展错误信息，应用程序可以调用 GetLastError，这会返回以下错误代码之一：

ERROR_INSUFFICIENT_BUFFER。提供的缓冲区大小不够大，或者错误地设置为 NULL。
ERROR_INVALID_DATA。数据无效。
ERROR_INVALID_FLAGS。为标志提供的值无效。
ERROR_INVALID_PARAMETER。任何参数值都无效。
ERROR_MOD_NOT_FOUND。找不到模块。
ERROR_OUTOFMEMORY。没有足够的存储空间可用于完成此操作。
ERROR_PROC_NOT_FOUND。找不到所需的过程。

注解

lpSrcStr 和 lpDestStr 参数的值不能相同。如果它们相同，函数将失败并ERROR_INVALID_PARAMETER。

Unicode 中的兼容区域由0xF900 0xFFEF范围内的字符组成，这些字符分配给其他字符编码标准中的字符，但实际上是 Unicode 中已有的字符的变体。兼容性区域用于支持到这些标准的往返映射。应用程序可以使用 MAP_FOLDCZONE 标志来避免支持兼容区域中的字符重复。

从 Windows Vista 开始： 此函数支持 Unicode 规范化。映射所有 Unicode 兼容性字符。

从 Windows Vista 开始： MAP_FOLDCZONE、MAP_PRECOMPOSED和MAP_COMPOSITE标志指示的转换使用 Unicode 规范化形式 KC、C 和 D (通过 NormalizeString 函数) 进行映射。

从Windows 8开始：函数的 ANSI 版本在 Winnls.h 中声明，Unicode 版本在 Stringapiset.h 中声明。在Windows 8之前，这两个版本都在 Winnls.h 中声明。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	winnls.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll