Fungsi NormalizeString (winnls.h)

Artikel
08/27/2023

Menormalkan karakter string teks sesuai dengan Unicode 4.0 TR#15. Untuk informasi selengkapnya, lihat Menggunakan Normalisasi Unicode untuk Mewakili String.

Sintaks

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

Parameter

[in] NormForm

Formulir normalisasi yang akan digunakan. NORM_FORM menentukan formulir normalisasi Unicode standar.

[in] lpSrcString

Penunjuk ke string sumber yang tidak dinormalisasi.

[in] cwSrcLength

Panjang, dalam karakter, dari buffer yang berisi string sumber. Aplikasi dapat mengatur parameter ini ke -1 jika fungsi harus mengasumsikan string dihentikan null dan menghitung panjang secara otomatis.

[out, optional] lpDstString

Penunjuk ke buffer tempat fungsi mengambil string tujuan. Atau, parameter ini berisi NULL jika cwDstLength diatur ke 0.

Catatan Fungsi tidak menghentikan string null jika panjang string input ditentukan secara eksplisit tanpa karakter null yang mengakhiri. Untuk menghentikan string output null, aplikasi harus menentukan -1 atau secara eksplisit menghitung karakter null yang mengakhiri untuk string input.

[in] cwDstLength

Panjang, dalam karakter, dari buffer yang berisi string tujuan. Atau, aplikasi dapat mengatur parameter ini ke 0 untuk meminta fungsi mengembalikan ukuran yang diperlukan untuk buffer tujuan.

Mengembalikan nilai

Mengembalikan panjang string yang dinormalisasi dalam buffer tujuan. Jika cwDstLength diatur ke 0, fungsi mengembalikan perkiraan panjang buffer yang diperlukan untuk melakukan konversi aktual.

Jika string dalam buffer input dihentikan null atau jika cwSrcLength adalah -1, string yang ditulis ke buffer tujuan dihentikan null dan panjang string yang dikembalikan menyertakan karakter null yang mengakhiri.

Fungsi mengembalikan nilai yang kurang dari atau sama dengan 0 jika tidak berhasil. Untuk mendapatkan informasi kesalahan yang diperluas, aplikasi dapat memanggil GetLastError, yang dapat mengembalikan salah satu kode kesalahan berikut:

ERROR_INSUFFICIENT_BUFFER. Ukuran buffer yang disediakan tidak cukup besar, atau salah diatur ke NULL.
ERROR_INVALID_PARAMETER. Salah satu nilai parameter tidak valid.
ERROR_NO_UNICODE_TRANSLATION. Unicode tidak valid ditemukan dalam string. Nilai yang dikembalikan adalah negatif dari indeks lokasi kesalahan dalam string input.
ERROR_SUCCESS. Tindakan berhasil diselesaikan tetapi tidak menghasilkan hasil.

Keterangan

Beberapa karakter Unicode memiliki beberapa representasi biner yang setara yang terdiri dari set menggabungkan dan/atau karakter Unicode komposit. Standar Unicode mendefinisikan proses yang disebut normalisasi yang mengembalikan satu representasi biner ketika diberikan salah satu representasi biner karakter yang setara. Normalisasi dapat dilakukan dengan beberapa algoritma, yang disebut bentuk normalisasi, yang mematuhi aturan yang berbeda, seperti yang dijelaskan dalam Menggunakan Normalisasi Unicode untuk Mewakili String. Win32 dan .NET Framework saat ini mendukung formulir normalisasi C, D, KC, dan KD, seperti yang didefinisikan dalam Unicode Standard Annex #15: Formulir Normalisasi Unicode. String yang dinormalisasi biasanya dievaluasi dengan perbandingan ordinal.

Kode berikut menunjukkan penggunaan perkiraan panjang buffer:

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:

Tidak lagi didukung.

File header dan DLL yang diperlukan adalah bagian dari API Mitigasi Nama Domain Internasional Microsoft (IDN), yang tidak lagi tersedia untuk diunduh.

Contoh

Contoh yang menunjukkan penggunaan fungsi ini dapat ditemukan di NLS: Sampel Normalisasi Unicode.

Persyaratan


Klien minimum yang didukung	Windows Vista [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	winnls.h (termasuk Windows.h)
DLL	Normaliz.dll
Redistribusi	API Mitigasi Nama Domain Internasional Microsoft (IDN) diWindows XP dengan SP2 dan yang lebih baru, atauWindows Server 2003 dengan SP1