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 的值，如果該值不成功則為 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 的一部分，無法再下載。

範例

此函式的使用範例可在 NLS：Unicode 正規化範例中找到。

規格需求


最低支援的用戶端	Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2008 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	winnls.h (包含 Windows.h)
Dll	Normaliz.dll
可轉散發套件	Microsoft 國際化功能變數名稱 (IDN) SP2 和更新版本之 Windows XP 上的風險降低 API，或使用 SP1 的Windows Server 2003