Fungsi LCMapStringA (winnls.h)

Artikel
03/08/2023

Untuk lokal yang ditentukan oleh pengidentifikasi, memetakan satu string karakter input ke string karakter input lainnya menggunakan transformasi tertentu, atau menghasilkan kunci pengurutan untuk string input.

Catatan Untuk alasan interoperabilitas, aplikasi harus lebih memilih fungsi LCMapStringEx ke LCMapString karena Microsoft bermigrasi ke penggunaan nama lokal alih-alih pengidentifikasi lokal untuk lokal baru. Rekomendasi ini berlaku terutama untuk lokal kustom, termasuk yang dibuat oleh Microsoft. Aplikasi apa pun yang hanya akan dijalankan pada Windows Vista dan yang lebih baru harus menggunakan LCMapStringEx.

Sintaks

int LCMapStringA(
  [in]            LCID   Locale,
  [in]            DWORD  dwMapFlags,
  [in]            LPCSTR lpSrcStr,
  [in]            int    cchSrc,
  [out, optional] LPSTR  lpDestStr,
  [in]            int    cchDest
);

Parameter

[in] Locale

Pengidentifikasi lokal yang menentukan lokal. Anda dapat menggunakan makro MAKELCID untuk membuat pengidentifikasi lokal atau menggunakan salah satu nilai yang telah ditentukan sebelumnya berikut ini.

Pengidentifikasi lokal kustom berikut ini juga didukung.

[in] dwMapFlags

Bendera yang menentukan jenis transformasi yang akan digunakan selama pemetaan string atau jenis kunci pengurutan yang akan dihasilkan. Untuk definisi terperinci, lihat parameter dwMapFlags dari LCMapStringEx.

[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 ke nilai negatif apa pun untuk menentukan bahwa string sumber dihentikan null. Dalam hal ini, jika LCMapString 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 pada posisi apa pun.
String tujuan dapat berisi jumlah byte ganjil. Bendera LCMAP_BYTEREV hanya membalikkan jumlah byte yang merata. Byte terakhir (posisi ganjil) di kunci pengurutan tidak dibalik.

Jika penelepon secara eksplisit meminta subset string, string tujuan tidak menyertakan karakter null yang mengakhiri kecuali penelepon 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 cased yang dikembalikan menjadi panjang yang berbeda.

[in] cchDest

Ukuran, dalam karakter, dari string tujuan yang ditunjukkan oleh lpDestStr. Jika aplikasi menggunakan fungsi untuk pemetaan string, aplikasi menyediakan 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 menyediakan 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 pengurutan.

Mengembalikan nilai

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 pemetaan string, maka akan 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 disediakan untuk bendera tidak valid.
ERROR_INVALID_PARAMETER. Salah satu nilai parameter tidak valid.

ERROR_INSUFFICIENT_BUFFER. Ukuran buffer yang disediakan tidak cukup besar, atau salah diatur ke NULL.
ERROR_INVALID_FLAGS. Nilai yang disediakan untuk bendera tidak valid.
ERROR_INVALID_PARAMETER. Salah satu nilai parameter tidak valid.

Keterangan

Lihat Keterangan untuk LCMapStringEx.

Versi ANSI dari LCMapString memetakan string ke dan dari Unicode berdasarkan halaman kode Windows (ANSI) default yang terkait dengan lokal yang ditentukan. Ketika versi ANSI dari fungsi ini digunakan dengan lokal khusus Unicode, fungsi dapat berhasil karena sistem operasi menggunakan nilai CP_ACP, mewakili halaman kode WINDOWS ANSI default sistem. Namun, karakter yang tidak ditentukan di halaman kode sistem muncul dalam string sebagai tanda tanya (?).

Catatan

Header winnls.h mendefinisikan LCMapString sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan


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