NormalizeString 函数 (winnls.h)

项目
08/27/2023

根据 Unicode 4.0 TR#15 规范化文本字符串的字符。有关详细信息，请参阅使用 Unicode 规范化来表示字符串。

语法

int NormalizeString(
  [in]            NORM_FORM NormForm,
  [in]            LPCWSTR   lpSrcString,
  [in]            int       cwSrcLength,
  [out, optional] LPWSTR    lpDstString,
  [in]            int       cwDstLength
);

参数

[in] NormForm

要使用的规范化形式。 NORM_FORM 指定标准 Unicode 规范化形式。

[in] lpSrcString

指向非规范化源字符串的指针。

[in] cwSrcLength

包含源字符串的缓冲区的长度（以字符为单位）。如果函数假定字符串以 null 结尾并自动计算长度，则应用程序可以将此参数设置为 -1。

[out, optional] lpDstString

指向函数在其中检索目标字符串的缓冲区的指针。或者，如果 cwDstLength 设置为 0，则此参数包含 NULL。

注意如果显式指定了输入字符串长度且没有终止 null 字符，则函数不会以 null 结尾。若要以 null 结尾输出字符串，应用程序应指定 -1 或显式计算输入字符串的终止 null 字符。

[in] cwDstLength

包含目标字符串的缓冲区的长度（以字符为单位）。或者，应用程序可以将此参数设置为 0，以请求函数返回目标缓冲区所需的大小。

返回值

返回目标缓冲区中规范化字符串的长度。如果 cwDstLength 设置为 0，则函数返回执行实际转换所需的估计缓冲区长度。

如果输入缓冲区中的字符串以 null 结尾，或者 cwSrcLength 为 -1，则写入目标缓冲区的字符串以 null 结尾，返回的字符串长度包括终止 null 字符。

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

ERROR_INSUFFICIENT_BUFFER。提供的缓冲区大小不够大，或者错误地设置为 NULL。
ERROR_INVALID_PARAMETER。任何参数值都无效。
ERROR_NO_UNICODE_TRANSLATION。在字符串中发现无效的 Unicode。返回值是输入字符串中错误位置的索引的负值。
ERROR_SUCCESS。操作已成功完成，但未产生任何结果。

注解

某些 Unicode 字符具有多个等效的二进制表示形式，由组合和/或复合 Unicode 字符集组成。 Unicode 标准定义了一个称为规范化的过程，当给定字符的任何等效二进制表示形式时，该流程将返回一个二进制表示形式。规范化可以使用多种算法（称为规范化形式）来执行，这些算法遵循不同的规则，如使用 Unicode 规范化来表示字符串中所述。 Win32 和 .NET Framework目前支持规范化形式 C、D、KC 和 KD，如 Unicode 标准附件 #15：Unicode 规范化形式所定义。规范化字符串通常通过序号比较进行计算。

以下代码演示了缓冲区长度估算的用法：

const int maxIterations = 10;
LPWSTR strResult = NULL;
HANDLE hHeap = GetProcessHeap();

int iSizeEstimated = NormalizeString(form, strInput, -1, NULL, 0);
for (int i = 0; i < maxIterations; i++)
{
    if (strResult)
        HeapFree(hHeap, 0, strResult);
    strResult = (LPWSTR)HeapAlloc(hHeap, 0, iSizeEstimated * sizeof (WCHAR));
    iSizeEstimated = NormalizeString(form, strInput, -1, strResult, iSizeEstimated);
 
    if (iSizeEstimated > 0)
        break; // success 
 
    if (iSizeEstimated <= 0)
    {
        DWORD dwError = GetLastError();
        if (dwError != ERROR_INSUFFICIENT_BUFFER) break; // Real error, not buffer error 
 
        // New guess is negative of the return value. 
        iSizeEstimated = -iSizeEstimated;
    }
}

Windows XP、Windows Server 2003：

不再支持。

所需的头文件和 DLL 是 Microsoft 国际化域名 (IDN) 缓解 API 的一部分，这些 API 不再可供下载。

示例

可在 NLS：Unicode 规范化示例中找到显示此函数用法的示例。

要求


最低受支持的客户端	Windows Vista [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2008 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	winnls.h (包括 Windows.h)
DLL	Normaliz.dll
可再发行组件	Windows XP SP2 及更高版本或 Windows Server 2003 SP1 上的 Microsoft 国际化域名 (IDN) 缓解 API