Fungsi FoldStringW (stringapiset.h)

Artikel
08/26/2023

Memetakan satu string Unicode ke string lain, melakukan transformasi yang ditentukan. Untuk gambaran umum penggunaan fungsi string, lihat String.

Hati Menggunakan FoldString salah dapat membahayakan keamanan aplikasi Anda. String yang tidak dipetakan dengan benar dapat menghasilkan input yang tidak valid. Uji string untuk memastikan string tersebut valid sebelum menggunakannya dan menyediakan penangan kesalahan. Untuk informasi selengkapnya, lihat Pertimbangan Keamanan: Fitur Internasional.

Sintaks

int FoldStringW(
  [in]            DWORD                         dwMapFlags,
  [in]            _In_NLS_string_(cchSrc)LPCWCH lpSrcStr,
  [in]            int                           cchSrc,
  [out, optional] LPWSTR                        lpDestStr,
  [in]            int                           cchDest
);

Parameter

[in] dwMapFlags

Bendera yang menentukan jenis transformasi yang akan digunakan selama pemetaan string. Parameter ini bisa menjadi kombinasi dari nilai berikut.

Bendera	Makna
MAP_COMPOSITE	Petakan karakter beraksen ke karakter yang diurai, yaitu karakter di mana karakter dasar dan satu atau beberapa karakter nonspacing masing-masing memiliki nilai titik kode yang berbeda. Misalnya, Ä diwakili oleh A + ̈: HURUF LATIN KAPITAL A (U+0041) + MENGGABUNGKAN DIAERESIS (U+0308). Bendera ini setara dengan formulir normalisasi D di Windows Vista. Perhatikan bahwa bendera ini tidak dapat digunakan dengan MB_PRECOMPOSED.
MAP_EXPAND_LIGATURES	Perluas semua karakter ligatur sehingga diwakili oleh dua karakter yang setara. Misalnya, ligatur "æ" (U+00e6) meluas ke dua karakter "a" (U+0061) + "e" (U+0065). Nilai ini tidak dapat digabungkan dengan MAP_PRECOMPOSED atau MAP_COMPOSITE.
MAP_FOLDCZONE	Lipat karakter zona kompatibilitas ke dalam setara Unicode standar. Bendera ini setara dengan bentuk normalisasi KD di Windows Vista, jika bendera MAP_COMPOSITE juga diatur. Jika bendera komposit tidak diatur (default), bendera ini setara dengan formulir normalisasi KC di Windows Vista.
MAP_FOLDDIGITS	Petakan semua digit ke karakter Unicode 0 hingga 9.
MAP_PRECOMPOSED	Petakan karakter beraksen ke karakter yang telah diolah sebelumnya, di mana aksen dan karakter dasar digabungkan menjadi satu nilai karakter. Bendera ini setara dengan formulir normalisasi C di Windows Vista. Nilai ini tidak dapat digabungkan dengan MAP_COMPOSITE.

[in] lpSrcStr

Penunjuk ke string sumber yang dipetakan fungsi.

[in] cchSrc

Ukuran, dalam karakter, dari string sumber yang ditunjukkan oleh lpSrcStr, tidak termasuk karakter null yang mengakhiri. Aplikasi dapat mengatur parameter ke nilai negatif apa pun untuk menentukan bahwa string sumber dihentikan null. Dalam hal ini, fungsi menghitung panjang string secara otomatis, dan null-mengakhiri string yang dipetakan yang ditunjukkan oleh lpDestStr.

[out, optional] lpDestStr

Penunjuk ke buffer tempat fungsi ini mengambil string yang dipetakan.

[in] cchDest

Ukuran, dalam karakter, dari string tujuan yang ditunjukkan oleh lpDestStr. Jika spasi untuk karakter null yang mengakhiri disertakan dalam cchSrc, cchDest juga harus menyertakan spasi untuk karakter null yang mengakhiri.

Aplikasi dapat mengatur cchDest ke 0. Dalam hal ini, fungsi tidak menggunakan parameter lpDestStr dan mengembalikan ukuran buffer yang diperlukan untuk string yang dipetakan. Jika bendera MAP_FOLDDIGITS ditentukan, nilai yang dikembalikan adalah ukuran maksimum yang diperlukan, bahkan jika jumlah karakter aktual yang diperlukan lebih kecil dari ukuran maksimum. Jika ukuran maksimum tidak dilewatkan, fungsi gagal dengan ERROR_INSUFFICIENT_BUFFER.

Mengembalikan nilai

Mengembalikan jumlah karakter dalam string yang diterjemahkan, termasuk karakter null yang mengakhiri, jika berhasil. Jika fungsi berhasil dan nilai cchDest adalah 0, nilai yang dikembalikan adalah ukuran buffer yang diperlukan untuk menahan string yang diterjemahkan, termasuk karakter null yang mengakhiri.

Fungsi ini mengembalikan 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_DATA. Data tidak valid.
ERROR_INVALID_FLAGS. Nilai yang diberikan untuk bendera tidak valid.
ERROR_INVALID_PARAMETER. Salah satu nilai parameter tidak valid.
ERROR_MOD_NOT_FOUND. Modul tidak ditemukan.
ERROR_OUTOFMEMORY. Penyimpanan tidak cukup tersedia untuk menyelesaikan operasi ini.
ERROR_PROC_NOT_FOUND. Prosedur yang diperlukan tidak ditemukan.

Keterangan

Nilai parameter lpSrcStr dan lpDestStr tidak boleh sama. Jika sama, fungsi gagal dengan ERROR_INVALID_PARAMETER.

Zona kompatibilitas di Unicode terdiri dari karakter dalam rentang 0xF900 melalui 0xFFEF yang ditetapkan ke karakter dari standar pengodean lain untuk karakter tetapi sebenarnya adalah varian karakter yang sudah ada di Unicode. Zona kompatibilitas digunakan untuk mendukung pemetaan pulang pergi ke standar ini. Aplikasi dapat menggunakan bendera MAP_FOLDCZONE untuk menghindari dukungan duplikasi karakter di zona kompatibilitas.

Dimulai dengan Windows Vista: Fungsi ini mendukung normalisasi Unicode. Semua karakter kompatibilitas Unicode dipetakan.

Dimulai dengan Windows Vista: Transformasi yang ditunjukkan oleh bendera MAP_FOLDCZONE, MAP_PRECOMPOSED, dan MAP_COMPOSITE menggunakan formulir normalisasi Unicode KC, C, dan D (melalui fungsi NormalizeString ) untuk melakukan pemetaan.

Dimulai dengan Windows 8: Versi ANSI dari fungsi dideklarasikan dalam Winnls.h dan versi Unicode dideklarasikan dalam Stringapiset.h. Sebelum Windows 8, kedua versi dideklarasikan dalam Winnls.h.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	stringapiset.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll