Fungsi LCMapStringEx (winnls.h)
Untuk lokal yang ditentukan berdasarkan nama, memetakan string karakter input ke yang lain menggunakan transformasi tertentu, atau menghasilkan kunci pengurutan untuk string input.
Sintaks
int LCMapStringEx(
[in, optional] LPCWSTR lpLocaleName,
[in] DWORD dwMapFlags,
[in] LPCWSTR lpSrcStr,
[in] int cchSrc,
[out, optional] LPWSTR lpDestStr,
[in] int cchDest,
[in, optional] LPNLSVERSIONINFO lpVersionInformation,
[in, optional] LPVOID lpReserved,
[in, optional] LPARAM sortHandle
);
Parameter
[in, optional] lpLocaleName
Arahkan ke nama lokal, atau salah satu nilai yang telah ditentukan sebelumnya berikut ini.
[in] dwMapFlags
Bendera yang menentukan jenis transformasi yang akan digunakan selama pemetaan string atau jenis kunci pengurutan yang akan dihasilkan. Parameter ini dapat memiliki nilai berikut.
| Bendera | Makna |
|---|---|
| LCMAP_BYTEREV | Gunakan pembalikan byte. Misalnya, jika aplikasi lolos 0x3450 0x4822, hasilnya 0x5034 0x2248. |
| LCMAP_FULLWIDTH | Gunakan karakter Unicode (wide) jika berlaku. Bendera dan LCMAP_HALFWIDTH ini saling eksklusif. Dengan bendera ini, pemetaan dapat menggunakan Formulir Normalisasi C meskipun karakter input sudah lebar penuh. Misalnya, string "は ゙" (yang sudah lebar penuh) dinormalisasi menjadi "ば". Lihat formulir normalisasi Unicode. |
| LCMAP_HALFWIDTH | Gunakan karakter sempit jika berlaku. Bendera dan LCMAP_FULLWIDTH ini saling eksklusif. |
| LCMAP_HIRAGANA | Petakan semua karakter katakana ke hiragana. Bendera dan LCMAP_KATAKANA ini saling eksklusif. |
| LCMAP_KATAKANA | Petakan semua karakter hiragana ke katakana. Bendera dan LCMAP_HIRAGANA ini saling eksklusif. |
| LCMAP_LINGUISTIC_CASING | Gunakan aturan linguistik untuk casing, alih-alih aturan sistem file (default). Bendera ini valid hanya dengan LCMAP_LOWERCASE atau LCMAP_UPPERCASE. |
| LCMAP_LOWERCASE | Untuk lokal dan skrip yang mampu menangani huruf besar dan huruf kecil, petakan semua karakter ke huruf kecil. |
| LCMAP_HASH | Mengembalikan hash dari bobot sortir mentah dari string. String yang muncul setara biasanya mengembalikan hash yang sama (misalnya, "hello" dan "HELLO" dengan LCMAP_IGNORECASE). Namun, beberapa kasus kompleks, seperti bahasa Asia Timur, dapat memiliki string serupa dengan bobot identik yang dibandingkan sama tetapi tidak mengembalikan hash yang sama. LCMAP_HASH mengharuskan buffer output berukuranof(int) |
| LCMAP_SIMPLIFIED_CHINESE | Petakan karakter tionghoa tradisional ke karakter Tionghoa yang disederhanakan. Bendera dan LCMAP_TRADITIONAL_CHINESE ini saling eksklusif. |
| LCMAP_SORTHANDLE Penggunaan handel pengurutan menghasilkan peningkatan performa minimal dan tidak disarankan. |
Mengembalikan token yang mewakili parameter pengurutan yang diselesaikan untuk lokal (seperti nama lokal), sehingga panggilan mendatang dapat meneruskan NULL nama pengurutan dan meneruskan handel pengurutan yang dikueri sebelumnya sebagai parameter terakhir (sortHandle) dalam panggilan berikutnya ke CompareStringEx atau LCMapStringEx.LCMAP_SORTHANDLE mengharuskan buffer output berukuranof (lparam) |
| LCMAP_SORTKEY | Menghasilkan kunci pengurutan yang dinormalisasi. Jika bendera LCMAP_SORTKEY tidak ditentukan, fungsi melakukan pemetaan string. Untuk detail pengurutan pembuatan kunci dan pemetaan string, lihat bagian Keterangan. |
| LCMAP_TITLECASE | Windows 7: Petakan semua karakter ke huruf besar/kecil, di mana huruf pertama dari setiap kata utama dikapitalisasi. |
| LCMAP_TRADITIONAL_CHINESE | Petakan karakter Tionghoa yang disederhanakan ke karakter Tionghoa tradisional. Bendera dan LCMAP_SIMPLIFIED_CHINESE ini saling eksklusif. |
| LCMAP_UPPERCASE | Untuk lokal dan skrip yang mampu menangani huruf besar dan huruf kecil, petakan semua karakter ke huruf besar. |
Bendera berikut dapat digunakan sendiri, satu sama lain, atau dengan bendera LCMAP_SORTKEY dan/atau LCMAP_BYTEREV. Namun, mereka tidak dapat digabungkan dengan bendera lain yang tercantum di atas.
Bendera yang tercantum di bawah ini hanya digunakan dengan bendera LCMAP_SORTKEY.
[in] lpSrcStr
Penunjuk ke string sumber yang dipetakan atau digunakan fungsi untuk mengurutkan pembuatan kunci. String ini tidak boleh memiliki ukuran 0.
[in] cchSrc
Ukuran, dalam karakter, dari string sumber yang ditunjukkan oleh lpSrcStr. Ukuran string sumber dapat mencakup karakter null yang mengakhiri, tetapi tidak harus. Jika karakter null yang mengakhiri disertakan, perilaku pemetaan fungsi tidak sangat terpengaruh karena karakter null yang mengakhiri dianggap tidak dapat diurutkan dan selalu memetakan ke dirinya sendiri.
Aplikasi dapat mengatur parameter ini ke nilai negatif apa pun untuk menentukan bahwa string sumber dihentikan null. Dalam hal ini, jika LCMapStringEx digunakan dalam mode pemetaan string-nya, fungsi menghitung panjang string itu sendiri, dan null-mengakhiri string yang dipetakan yang ditunjukkan oleh lpDestStr.
Aplikasi tidak dapat mengatur parameter ini ke 0.
[out, optional] lpDestStr
Penunjuk ke buffer tempat fungsi ini mengambil string yang dipetakan atau kunci pengurutan.
Jika aplikasi menggunakan fungsi untuk menghasilkan kunci pengurutan (LCMAP_SORTKEY):
- Kunci sortir disimpan dalam buffer dan diperlakukan sebagai array byte buram. Nilai yang disimpan dapat mencakup 0 byte yang disematkan di posisi mana pun.
- String tujuan dapat berisi jumlah byte ganjil. Bendera LCMAP_BYTEREV hanya membalikkan jumlah byte yang merata. Byte terakhir (posisi ganjil) dalam kunci pengurutan tidak dibalik.
Jika penelepon secara eksplisit meminta subset string, string tujuan tidak menyertakan karakter null yang mengakhiri kecuali pemanggil menentukannya di cchDest.
Jika fungsi ini gagal, buffer tujuan mungkin berisi hasil parsial atau tidak ada hasil sama sekali. Dalam hal ini, semua hasil harus dianggap tidak valid.
Catatan
Saat mengatur LCMAP_UPPERCASE atau LCMAP_LOWERCASE, string tujuan dapat menggunakan buffer yang sama dengan string sumber. Namun, ini sangat tidak disarankan, karena beberapa kondisi dapat menyebabkan string kasus yang dikembalikan memiliki panjang yang berbeda.
[in] cchDest
Ukuran, dalam karakter, dari string tujuan yang ditunjukkan oleh lpDestStr. Jika aplikasi menggunakan fungsi untuk pemetaan string, aplikasi memasok jumlah karakter untuk parameter ini. Jika spasi untuk karakter null yang mengakhiri disertakan dalam cchSrc, cchDest juga harus menyertakan spasi untuk karakter null yang mengakhiri.
Jika aplikasi menggunakan fungsi untuk menghasilkan kunci pengurutan, aplikasi memasok jumlah byte untuk ukuran tersebut. Jumlah byte ini harus menyertakan ruang untuk kunci pengurutan 0x00 terminator.
Aplikasi dapat mengatur cchDest ke 0. Dalam hal ini, fungsi tidak menggunakan parameter lpDestStr dan mengembalikan ukuran buffer yang diperlukan untuk string yang dipetakan atau kunci sortir.
[in, optional] lpVersionInformation
Penunjuk ke struktur NLSVERSIONINFOEX yang berisi informasi versi tentang kemampuan NLS yang relevan; biasanya diambil dari GetNLSVersionEx.
Windows Vista, Windows 7: Dipesan; harus diatur ke NULL.
[in, optional] lpReserved
Dipesan; harus NULL.
[in, optional] sortHandle
Dipesan; harus 0.
Catatan
CompareStringEx dan LCMapStringEx dapat menentukan handel pengurutan (jika nama lokal null). Penggunaan ini tidak disarankan untuk sebagian besar aplikasi.
Nilai kembali
Jika fungsi berhasil saat digunakan untuk pemetaan string, fungsi mengembalikan jumlah karakter dalam string yang diterjemahkan (lihat cchSrc dan cchDest untuk detail selengkapnya).
Jika fungsi berhasil saat digunakan untuk menghasilkan kunci pengurutan, fungsi mengembalikan jumlah byte dalam kunci pengurutan.
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_FLAGS. Nilai yang diberikan untuk bendera tidak valid.
- ERROR_INVALID_PARAMETER. Salah satu nilai parameter tidak valid.
Keterangan
Aplikasi dapat menggunakan LCMapString atau LCMapStringEx untuk menghasilkan kunci pengurutan. Untuk melakukan ini, aplikasi menentukan LCMAP_SORTKEY untuk parameter dwMapFlags . Untuk informasi selengkapnya, lihat Menangani Pengurutan di Aplikasi Anda.
Catatan
Kunci sortir adalah aliran byte buram. Penelepon harus memperlakukannya sebagai array byte dengan panjang yang dikembalikan oleh API dan tidak bergantung pada struktur internal apa pun yang mungkin tampak ada. Nol, satu atau beberapa byte dalam kunci pengurutan yang dikembalikan bisa 0. Ketidakhadiran atau kehadiran byte nol seharusnya tidak diharapkan.
Cara lain bagi aplikasi Anda untuk menggunakan LCMapString atau LCMapStringEx adalah dalam string pemetaan. Dalam hal ini, aplikasi tidak menentukan LCMAP_SORTKEY untuk parameter dwMapFlags , tetapi memasok beberapa kombinasi bendera lainnya. Untuk informasi selengkapnya, lihat Menangani Pengurutan di Aplikasi Anda.
Dimulai di Windows Vista: Fungsi ini dapat menangani data dari lokal kustom. Data tidak dijamin sama dari komputer ke komputer atau antara eksekusi aplikasi. Jika aplikasi Anda harus mempertahankan atau mengirimkan data, lihat Menggunakan Data Lokal Persisten.
Dimulai di Windows 8: Jika aplikasi Anda meneruskan tag bahasa ke fungsi ini dari namespace Windows.Globalization, aplikasi harus terlebih dahulu mengonversi tag dengan memanggil ResolveLocaleName.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| 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) |
| Pustaka | Kernel32.lib |
| DLL | Kernel32.dll |