findNLSStringEx 函数 (winnls.h)

项目
08/27/2023

在名称指定的区域设置的另一个 Unicode 字符串中查找 (宽字符) 或其等效项的 Unicode 字符串。

谨慎由于具有非常不同的二进制表示形式的字符串可以比较为相同，因此此函数可能会引发某些安全问题。有关详细信息，请参阅安全注意事项：国际功能中的比较函数讨论。

语法

int FindNLSStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFindNLSStringFlags,
  [in]            LPCWSTR          lpStringSource,
  [in]            int              cchSource,
  [in]            LPCWSTR          lpStringValue,
  [in]            int              cchValue,
  [out, optional] LPINT            pcchFound,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

参数

[in, optional] lpLocaleName

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

[in] dwFindNLSStringFlags

指定查找操作详细信息的标志。这些标志互斥，FIND_FROMSTART为默认值。应用程序可以使用下表中定义的任何筛选标志，仅指定其中一个查找标志。如果应用程序未指定标志，则函数对指定的区域设置使用默认比较。如在应用程序中处理排序中所述，没有二进制比较模式。

值	含义
FIND_FROMSTART	搜索字符串，从字符串的第一个字符开始。
FIND_FROMEND	反向搜索字符串，从字符串的最后一个字符开始。
FIND_STARTSWITH	测试以确定 lpStringValue 指定的值是否为 lpStringSource 指示的源字符串中的第一个值。
FIND_ENDSWITH	测试以确定 lpStringValue 指定的值是否是 lpStringSource 指示的源字符串中的最后一个值。

应用程序可以将下面定义的筛选标志与查找标志结合使用。

值	含义
LINGUISTIC_IGNORECASE	在语言上适当时，在搜索中忽略大小写。有关详细信息，请参见“备注”部分。
LINGUISTIC_IGNOREDIACRITIC	在语言上适当时忽略音调符号。有关详细信息，请参见“备注”部分。注意当与分解字符（即基字符和一个或多个非节奏字符各自具有不同的码位值）一起使用时，此标志并不总是产生可预测的结果。
NORM_IGNORECASE	在搜索中忽略大小写。有关详细信息，请参见“备注”部分。
NORM_IGNOREKANATYPE	不要区分平假名和片假名字符。相应的平假名和片假名字符比较为相等。
NORM_IGNORENONSPACE	忽略非节奏字符。有关详细信息，请参见“备注”部分。
NORM_IGNORESYMBOLS	忽略符号和标点符号。
NORM_IGNOREWIDTH	忽略半角字符和全角字符之间的差异，例如 C a t == cat。全角窗体是中文和日文脚本中使用的格式差异。
NORM_LINGUISTIC_CASING	使用语言规则进行大小写，而不是使用文件系统规则 (默认) 。有关详细信息，请参见“备注”部分。

[in] lpStringSource

指向源字符串的指针，函数在其中搜索 lpStringValue 指定的字符串。

[in] cchSource

lpStringSource 指示的字符串的大小（以字符为单位，不包括终止 null 字符）。应用程序不能为此参数指定 0 或任何除 -1 以外的负数。如果源字符串以 null 结尾，则应用程序指定 -1，并且函数应自动计算大小。

[in] lpStringValue

指向搜索字符串的指针，函数在源字符串中搜索该字符串。

[in] cchValue

lpStringValue 指示的字符串的大小，以字符为单位，不包括终止 null 字符。应用程序不能为此参数指定 0 或任何除 -1 以外的负数。如果搜索字符串以 null 结尾，则应用程序指定 -1，并且函数应自动计算大小。

[out, optional] pcchFound

指向包含函数找到的字符串长度的缓冲区的指针。字符串可以比搜索字符串长或短。如果函数找不到搜索字符串，则不会修改此参数。

函数可以在此参数中检索 NULL 。在这种情况下，如果找到的字符串的长度与源字符串的长度不同，函数不会发出任何指示。

请注意， pcchFound 的值通常与 cchValue 中提供的值相同，但在以下情况下可能有所不同：

cchValue 中提供的值为负值。
字符串是等效的，但具有不同的长度。例如，“A”加“组合环” (U+0041 U+030A) 等效于 U+00c5) (“A Ring”。

[in, optional] lpVersionInformation

保留;必须为 NULL。

[in, optional] lpReserved

保留;必须为 NULL。

[in, optional] sortHandle

保留;必须为 0。

返回值

如果成功，则返回 lpStringSource 指示的源字符串中的从 0 开始的索引。结合 pcchFound 中的值，此索引提供源字符串中整个找到的字符串的确切位置。返回值 0 是源字符串中的无错误索引，匹配的字符串位于偏移量为 0 的源字符串中。

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

ERROR_INVALID_FLAGS。为标志提供的值无效。
ERROR_INVALID_PARAMETER。任何参数值都无效。
ERROR_SUCCESS。操作已成功完成，但未产生任何结果。

注解

此函数提供各种搜索选项，包括搜索方向、字符等效筛选和特定于区域设置的筛选。请注意，等效性取决于在函数调用中指定的区域设置和标志。筛选标志可以更改搜索结果。例如，当函数在执行搜索时忽略大小写或音调符号时，潜在的匹配会增加。

默认情况下，此函数将小写的“i”映射到大写的“I”，即使 Locale 参数指定土耳其 (土耳其) 或阿塞拜疆语 (阿塞拜疆) 也是如此。若要替代土耳其语或阿塞拜疆人的此行为，应用程序应指定NORM_LINGUISTIC_CASING。如果为正确的区域设置指定了此标志，则“ı” (小写无点 I) 是小写形式的“I” (大写无点 I) ，“i” (小写虚线 I) 是小写形式的“ı” (大写虚线 I) 。

对于许多脚本 (特别是拉丁语脚本) ，NORM_IGNORENONSPACE与LINGUISTIC_IGNOREDIACRITIC一致，NORM_IGNORECASE与LINGUISTIC_IGNORECASE一致，但以下情况例外：

NORM_IGNORENONSPACE忽略任何次要区别，无论它是否为音调符号。朝鲜语、日语、中文、印度语和其他语言的脚本将此区别用于音调符号以外的其他用途。 LINGUISTIC_IGNOREDIACRITIC只忽略实际音调符号，而不是只忽略第二个排序权重。
NORM_IGNORECASE忽略任何第三级区分，无论它是否实际上是语言案例。例如，在阿拉伯语和 Indic 脚本中，此标志区分字符的备用形式。但是，这些差异与语言大小写不一致。 LINGUISTIC_IGNORECASE只忽略实际的语言大小写，而不是忽略第三个排序权重。

与其他 NLS API 函数（失败返回 0）不同，如果失败，此函数返回 -1。成功后，它将返回从 0 开始的索引。使用此索引有助于函数避免逐个错误和单字符缓冲区溢出。

此函数是少数调用 SetLastError 的 NLS 函数之一，即使它成功也是如此。它发出此调用以在无法匹配搜索字符串时清除线程中的最后一个错误。这将清除 GetLastError 返回的值。

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

要求


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