LCMapStringEx 函数 (winnls.h)

  • 项目

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

注意 如果设计为仅在 Windows Vista 及更高版本上运行，则应用程序应优先调用 LCMapString 。

 

语法

int LCMapStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwMapFlags,
  [in]            LPCWSTR          lpSrcStr,
  [in]            int              cchSrc,
  [out, optional] LPWSTR           lpDestStr,
  [in]            int              cchDest,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

参数

[in, optional] lpLocaleName

指向 区域设置名称或以下预定义值之一的指针。

[in] dwMapFlags

指定在字符串映射期间使用的转换类型或要生成的排序键类型的标志。 此参数可以具有以下值。

标志 含义
LCMAP_BYTEREV 使用字节反转。 例如，如果应用程序传入0x3450 0x4822，则结果为0x5034 0x2248。
LCMAP_FULLWIDTH 如果适用，请使用 Unicode (宽) 字符。 此标志和LCMAP_HALFWIDTH是互斥的。 使用此标志时，即使输入字符已经是全角字符，映射也可以使用规范化形式 C。 例如，将字符串“は゛”（已是全角）规范化为“ば”。 请参阅 Unicode 范式。
LCMAP_HALFWIDTH 在适用的情况下使用窄字符。 此标志和LCMAP_FULLWIDTH互斥。
LCMAP_HIRAGANA 将所有片假名字符映射到平假名。 此标志和LCMAP_KATAKANA是互斥的。
LCMAP_KATAKANA 将所有平假名字符映射到片假名。 此标志和LCMAP_HIRAGANA是互斥的。
LCMAP_LINGUISTIC_CASING 使用语言规则进行大小写，而不是文件系统规则 (默认) 。 此标志仅对 LCMAP_LOWERCASE 或 LCMAP_UPPERCASE 有效。
LCMAP_LOWERCASE 对于能够处理大写和小写的区域设置和脚本，请将所有字符映射到小写。
LCMAP_HASH 返回字符串的原始排序权重的哈希。

看起来等效的字符串通常返回相同的哈希 (例如，“hello”和“HELLO”与LCMAP_IGNORECASE) 。 但是，某些复杂情况（如东亚语言）可以具有具有相同权重的类似字符串，这些字符串比较为相等，但不返回相同的哈希。

LCMAP_HASH要求输出缓冲区的大小为 (int)
LCMAP_SIMPLIFIED_CHINESE 将繁体中文映射到简体中文字符。 此标志和LCMAP_TRADITIONAL_CHINESE是互斥的。
LCMAP_SORTHANDLE
使用排序句柄可最大程度地提高性能，不建议这样做。		 返回表示区域设置 (解析排序参数（如区域设置名称) ）的标记，以便将来的调用可以传递 NULL 排序名称，并将以前查询的排序句柄作为最后一个参数 (sortHandle) 在对 CompareStringEx 或 LCMapStringEx 的后续调用中传递。

LCMAP_SORTHANDLE要求输出缓冲区的大小为 (lparam)
LCMAP_SORTKEY 生成规范化排序键。 如果未指定LCMAP_SORTKEY标志，函数将执行字符串映射。 有关排序键生成和字符串映射的详细信息，请参阅备注部分。
LCMAP_TITLECASE Windows 7： 将所有字符映射到标题大写，其中每个主要单词的第一个字母都大写。
LCMAP_TRADITIONAL_CHINESE 将简体中文字符映射到繁体中文。 此标志和LCMAP_SIMPLIFIED_CHINESE是互斥的。
LCMAP_UPPERCASE 对于能够处理大写和小写的区域设置和脚本，将所有字符映射到大写。

以下标志可以单独使用，可以相互使用，也可以与LCMAP_SORTKEY和/或LCMAP_BYTEREV标志一起使用。 但是，它们不能与上面列出的其他标志组合使用。

标志 含义
NORM_IGNORENONSPACE
 忽略非节奏字符。 对于许多脚本 (尤其是拉丁语脚本) ，NORM_IGNORENONSPACE与LINGUISTIC_IGNOREDIACRITIC一致。
注意 NORM_IGNORENONSPACE忽略任何次要区别，无论它是否为音调符号。 朝鲜语、日语、中文和印度语等语言的脚本将这种区别用于除音调符号以外的目的。 LINGUISTIC_IGNOREDIACRITIC会导致函数仅忽略实际音调符号，而不是忽略第二个排序权重。
 
NORM_IGNORESYMBOLS
 忽略符号和标点。
 

下面列出的标志仅与 LCMAP_SORTKEY 标志一起使用。

标志 含义
LINGUISTIC_IGNORECASE
 在语言上适当时忽略大小写。
LINGUISTIC_IGNOREDIACRITIC
 在语言上适当时忽略非节奏字符。
注意 当与分解字符一起使用时，此标志并不总是产生可预测的结果，即基字符和一个或多个非节奏字符各自具有不同的码位值。
 
NORM_IGNORECASE
 忽略大小写。 对于许多脚本 (尤其是拉丁语脚本) ，NORM_IGNORECASE与LINGUISTIC_IGNORECASE一致。
注意 NORM_IGNORECASE忽略任何第三级区别，无论它是否实际上是语言大小写。 例如，在阿拉伯语和印度语脚本中，此标志区分字符的备用形式，但差异与语言大小写不对应。 LINGUISTIC_IGNORECASE会导致函数仅忽略实际语言大小写，而不是忽略第三个排序权重。
 
注意 对于 (DBCS) 区域设置的双字节字符集，NORM_IGNORECASE对所有 Unicode 字符以及窄 (一字节) 字符（包括希腊文和西里尔文字符）产生影响。
 
NORM_IGNOREKANATYPE
 不要区分平假名和片假名字符。 对应的平假名和片假名字符比较相等。
NORM_IGNOREWIDTH
 忽略半角字符和全角字符之间的差异，例如 C a t == cat。 全角窗体是中文和日文脚本中使用的格式差异。
NORM_LINGUISTIC_CASING
 使用语言规则进行大小写，而不是文件系统规则 (默认) 。
SORT_DIGITSASNUMBERS
 Windows 7： 在排序过程中，将数字视为数字，例如，在“10”前排序“2”。
SORT_STRINGSORT
 将标点视为符号。

[in] lpSrcStr

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

[in] cchSrc

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

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

应用程序无法将此参数设置为 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 参数，并返回映射字符串或排序键所需的缓冲区大小。

[in, optional] lpVersionInformation

指向包含相关 NLS 功能的版本信息的 NLSVERSIONINFOEX 结构的指针;通常从 GetNLSVersionEx 检索。

Windows Vista、Windows 7： 保留;必须设置为 NULL。

[in, optional] lpReserved

保留;必须为 NULL。

[in, optional] sortHandle

保留;必须为 0。

注意

如果区域设置名称为 null ) ，CompareStringEx 和 LCMapStringEx 可以指定排序句柄 (。 对于大多数应用，不建议使用此用法。

返回值

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

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

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

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

注解

应用程序可以使用 LCMapString 或 LCMapStringEx 生成排序键。 为此，应用程序为 dwMapFlags 参数指定LCMAP_SORTKEY。 有关详细信息，请参阅 处理应用程序中的排序。

注意

排序键是不透明的字节流。 调用方应将它们视为 API 返回的长度的字节数组，而不依赖于任何可能看起来存在的内部结构。 零，返回的排序键中的一个或多个字节可以为 0。 不应期望不存在或存在零字节。

应用程序使用 LCMapString 或 LCMapStringEx 的另一种方法是映射字符串。 在这种情况下，应用程序不会为 dwMapFlags 参数指定LCMAP_SORTKEY，而是提供标志的其他一些组合。 有关详细信息，请参阅 处理应用程序中的排序。

从 Windows Vista 开始： 此函数可以处理 来自自定义区域设置的数据。 不保证数据在计算机之间或应用程序运行之间的数据相同。 如果应用程序必须保留或传输数据，请参阅 使用永久性区域设置数据。

从Windows 8开始：如果你的应用将语言标记从 Windows.Globalization 命名空间传递到此函数，它必须首先通过调用 ResolveLocaleName 来转换标记。

要求

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

另请参阅

CompareString

FindNLSStringEx

GetNLSVersionEx

处理应用程序中的排序

LCMapString

国家语言支持

国家语言支持函数