LCMapStringA 函数 (winnls.h)

项目
08/27/2023

对于标识符指定的区域设置，使用指定的转换将一个输入字符串映射到另一个输入字符串，或者为输入字符串生成排序键。

注意出于互操作性原因，应用程序应优先使用 LCMapStringEx 函数而不是 LCMapString ，因为 Microsoft 正在迁移到使用区域设置名称而不是新区域设置的区域设置标识符。此建议尤其适用于自定义区域设置，包括 Microsoft 创建的区域设置。将仅在 Windows Vista 和更高版本上运行的任何应用程序都应使用 LCMapStringEx。

语法

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

参数

[in] Locale

指定区域设置的区域设置标识符。可以使用 MAKELCID 宏创建区域设置标识符或使用以下预定义值之一。

还支持以下自定义区域设置标识符。

[in] dwMapFlags

指定要在字符串映射期间使用的转换类型或要生成的排序键类型的标志。有关详细定义，请参阅 LCMapStringEx 的 dwMapFlags 参数。

[in] lpSrcStr

指向函数映射或用于排序键生成的源字符串的指针。此字符串的大小不能为 0。

[in] cchSrc

lpSrcStr 指示的源字符串的大小（以字符为单位）。源字符串的大小可以包含终止 null 字符，但不一定。如果包含终止 null 字符，则函数的映射行为不会受到很大影响，因为终止 null 字符被视为不可排序，并且始终映射到自身。

应用程序可以将参数设置为任何负值，以指定以 null 结尾的源字符串。在这种情况下，如果在其字符串映射模式下使用 LCMapString ，则该函数将计算字符串长度本身，并将 lpDestStr 指示的映射字符串终止为 null。

应用程序无法将此参数设置为 0。

[out, optional] lpDestStr

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

如果应用程序使用函数生成排序键 (LCMAP_SORTKEY) ：

排序键存储在缓冲区中，并被视为不透明的字节数组。存储的值可以包含任意位置的嵌入 0 个字节。
目标字符串可以包含奇数字节。 LCMAP_BYTEREV标志仅反转偶数个字节。排序键中的最后一个字节 (奇数定位) 不会反转。

如果调用方显式请求字符串的子集，则目标字符串不包含终止 null 字符，除非调用方在 cchDest 中指定了该字符。

如果此函数失败，则目标缓冲区可能包含部分结果或根本没有结果。在这种情况下，所有结果都应被视为无效。

注意

设置LCMAP_UPPERCASE或LCMAP_LOWERCASE时，目标字符串可以使用与源字符串相同的缓冲区。但是，强烈建议不要这样做，因为某些条件可能会导致返回的大小写字符串的长度不同。

[in] cchDest

lpDestStr 指示的目标字符串的大小（以字符为单位）。如果应用程序使用函数进行字符串映射，它将提供此参数的字符计数。如果 cchSrc 中包含终止 null 字符的空间， 则 cchDest 还必须包含终止 null 字符的空间。

如果应用程序使用函数生成排序键，它将提供大小的字节计数。此字节计数必须包含排序键0x00终止符的空间。

应用程序可以将 cchDest 设置为 0。在这种情况下，函数不使用 lpDestStr 参数，并返回映射字符串或排序键所需的缓冲区大小。

返回值

如果函数在用于字符串映射时成功，它将返回已翻译字符串中的字符数 (有关) 的更多详细信息，请参阅 cchSrc 和 cchDest 。

如果函数在用于字符串映射时成功，它将返回排序键中的字节数。

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

ERROR_INSUFFICIENT_BUFFER。提供的缓冲区大小不够大，或者错误地设置为 NULL。
ERROR_INVALID_FLAGS。为标志提供的值无效。
ERROR_INVALID_PARAMETER。任何参数值都无效。

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

ERROR_INSUFFICIENT_BUFFER。提供的缓冲区大小不够大，或者错误地设置为 NULL。
ERROR_INVALID_FLAGS。为标志提供的值无效。
ERROR_INVALID_PARAMETER。任何参数值都无效。

注解

请参阅 LCMapStringEx 的备注。

LCMapString 的 ANSI 版本基于与指定区域设置关联的默认 Windows (ANSI) 代码页，将字符串映射到 Unicode 和从 Unicode 映射字符串。当此函数的 ANSI 版本与仅限 Unicode 的区域设置一起使用时，该函数可以成功，因为操作系统使用表示系统默认 Windows ANSI 代码页的 CP_ACP 值。但是，系统代码页中未定义的字符在字符串中显示为问号 (？) 。

注意

winnls.h 标头将 LCMapString 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求


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