Fungsi WideCharToMultiByte (stringapiset.h)
Memetakan string UTF-16 (karakter lebar) ke string karakter baru. String karakter baru belum tentu dari set karakter multibyte.
Data yang dikonversi dari pengodean UTF-16 ke non-Unicode mengalami kehilangan data, karena halaman kode mungkin tidak dapat mewakili setiap karakter yang digunakan dalam data Unicode tertentu. Untuk informasi selengkapnya, lihat Pertimbangan Keamanan: Fitur Internasional.
Sintaks
int WideCharToMultiByte(
[in] UINT CodePage,
[in] DWORD dwFlags,
[in] _In_NLS_string_(cchWideChar)LPCWCH lpWideCharStr,
[in] int cchWideChar,
[out, optional] LPSTR lpMultiByteStr,
[in] int cbMultiByte,
[in, optional] LPCCH lpDefaultChar,
[out, optional] LPBOOL lpUsedDefaultChar
);
Parameter
[in] CodePage
Halaman kode untuk digunakan dalam melakukan konversi. Parameter ini dapat diatur ke nilai halaman kode apa pun yang diinstal atau tersedia dalam sistem operasi. Untuk daftar halaman kode, lihat Pengidentifikasi Halaman Kode. Aplikasi Anda juga dapat menentukan salah satu nilai yang ditunjukkan dalam tabel berikut.
[in] dwFlags
Bendera yang menunjukkan jenis konversi. Aplikasi dapat menentukan kombinasi nilai berikut. Fungsi ini bekerja lebih cepat ketika tidak ada bendera ini yang diatur. Aplikasi harus menentukan WC_NO_BEST_FIT_CHARS dan WC_COMPOSITECHECK dengan nilai tertentu WC_DEFAULTCHAR untuk mengambil semua kemungkinan hasil konversi. Jika ketiga nilai tidak disediakan, beberapa hasil akan hilang.
| Nilai | Makna | ||||||
|---|---|---|---|---|---|---|---|
|
Mengonversi karakter komposit, yang terdiri dari karakter dasar dan karakter nonspacing, masing-masing dengan nilai karakter yang berbeda. Terjemahkan karakter ini ke karakter yang telah dikompilasi sebelumnya, yang memiliki nilai karakter tunggal untuk kombinasi karakter dasar-nonspacing. Misalnya, dalam karakter è, e adalah karakter dasar dan tanda kubur aksen adalah karakter nonspacing. Catatan Windows biasanya mewakili untai (karakter) Unicode dengan data yang telah dikompios sebelumnya, yang membuat penggunaan bendera WC_COMPOSITECHECK tidak perlu.
Aplikasi Anda dapat menggabungkan WC_COMPOSITECHECK dengan salah satu bendera berikut, dengan default WC_SEPCHARS. Bendera ini menentukan perilaku fungsi ketika tidak ada pemetaan yang telah dikompresi sebelumnya untuk kombinasi karakter base-nonspacing dalam string Unicode yang tersedia. Jika tidak ada bendera ini yang disediakan, fungsi berperilaku seolah-olah bendera WC_SEPCHARS diatur. Untuk informasi selengkapnya, lihat WC_COMPOSITECHECK dan bendera terkait di bagian Keterangan .
|
||||||
|
Windows Vista dan yang lebih baru: Gagal (dengan mengembalikan 0 dan mengatur kode kesalahan terakhir ke ERROR_NO_UNICODE_TRANSLATION) jika karakter input yang tidak valid ditemui. Anda dapat mengambil kode kesalahan terakhir dengan panggilan ke GetLastError. Jika bendera ini tidak diatur, fungsi mengganti urutan ilegal dengan U+FFFD (dikodekan sesuai untuk codepage yang ditentukan) dan berhasil dengan mengembalikan panjang string yang dikonversi. Perhatikan bahwa bendera ini hanya berlaku ketika CodePage ditentukan sebagai CP_UTF8 atau 54936. Ini tidak dapat digunakan dengan nilai halaman kode lainnya. | ||||||
|
Terjemahkan karakter Unicode apa pun yang tidak diterjemahkan langsung ke setara multibyte ke karakter default yang ditentukan oleh lpDefaultChar. Dengan kata lain, jika menerjemahkan dari Unicode ke multibyte dan kembali ke Unicode lagi tidak menghasilkan karakter Unicode yang sama, fungsi menggunakan karakter default. Bendera ini dapat digunakan dengan sendirinya atau dalam kombinasi dengan bendera lain yang ditentukan.
Untuk string yang memerlukan validasi, seperti file, sumber daya, dan nama pengguna, aplikasi harus selalu menggunakan bendera WC_NO_BEST_FIT_CHARS. Bendera ini mencegah fungsi memetakan karakter ke karakter yang tampak serupa tetapi memiliki semantik yang sangat berbeda. Dalam beberapa kasus, perubahan semantik bisa ekstrem. Misalnya, simbol untuk peta "∞" (tak terbatas) ke 8 (delapan) di beberapa halaman kode. |
Untuk halaman kode yang tercantum di bawah ini, dwFlags harus 0. Jika tidak, fungsi gagal dengan ERROR_INVALID_FLAGS.
- 50220
- 50221
- 50222
- 50225
- 50227
- 50229
- 57002 hingga 57011
- 65000 (UTF-7)
- 42 (Simbol)
[in] lpWideCharStr
Arahkan ke string Unicode untuk dikonversi.
[in] cchWideChar
Ukuran, dalam karakter, dari string yang ditunjukkan oleh lpWideCharStr. Atau, parameter ini dapat diatur ke -1 jika string dihentikan null. Jika cchWideChar diatur ke 0, fungsi gagal.
Jika parameter ini adalah -1, fungsi memproses seluruh string input, termasuk karakter null yang mengakhiri. Oleh karena itu, string karakter yang dihasilkan memiliki karakter null yang mengakhiri, dan panjang yang dikembalikan oleh fungsi mencakup karakter ini.
Jika parameter ini diatur ke bilangan bulat positif, fungsi memproses jumlah karakter yang ditentukan dengan tepat. Jika ukuran yang disediakan tidak menyertakan karakter null yang mengakhiri, string karakter yang dihasilkan tidak dihentikan null, dan panjang yang dikembalikan tidak menyertakan karakter ini.
[out, optional] lpMultiByteStr
Penunjuk ke buffer yang menerima string yang dikonversi.
[in] cbMultiByte
Ukuran, dalam byte, dari buffer yang ditunjukkan oleh lpMultiByteStr. Jika nilai ini adalah 0, fungsi mengembalikan ukuran buffer yang diperlukan, dalam byte, termasuk karakter null yang mengakhiri, dan tidak menggunakan buffer lpMultiByteStr .
[in, optional] lpDefaultChar
Penunjuk ke karakter untuk digunakan jika karakter tidak dapat diwakili di halaman kode yang ditentukan. Aplikasi mengatur parameter ini ke NULL jika fungsinya adalah menggunakan nilai default sistem. Untuk mendapatkan karakter default sistem, aplikasi dapat memanggil fungsi GetCPInfo atau GetCPInfoEx .
Untuk pengaturan CP_UTF7 dan CP_UTF8 untuk CodePage, parameter ini harus diatur ke NULL. Jika tidak, fungsi gagal dengan ERROR_INVALID_PARAMETER.
[out, optional] lpUsedDefaultChar
Penunjuk ke bendera yang menunjukkan apakah fungsi telah menggunakan karakter default dalam konversi. Bendera diatur ke TRUE jika satu atau beberapa karakter dalam string sumber tidak dapat diwakili di halaman kode yang ditentukan. Jika tidak, bendera diatur ke FALSE. Parameter ini dapat diatur ke NULL.
Untuk pengaturan CP_UTF7 dan CP_UTF8 untuk CodePage, parameter ini harus diatur ke NULL. Jika tidak, fungsi gagal dengan ERROR_INVALID_PARAMETER.
Mengembalikan nilai
Jika berhasil, mengembalikan jumlah byte yang ditulis ke buffer yang diacu oleh lpMultiByteStr. Jika fungsi berhasil dan cbMultiByte adalah 0, nilai yang dikembalikan adalah ukuran yang diperlukan, dalam byte, untuk buffer yang ditunjukkan oleh lpMultiByteStr. Lihat juga dwFlags untuk informasi tentang bagaimana bendera WC_ERR_INVALID_CHARS memengaruhi nilai yang dikembalikan saat urutan yang tidak valid adalah input.
Fungsi 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.
- ERROR_NO_UNICODE_TRANSLATION. Unicode tidak valid ditemukan dalam string.
Keterangan
Pointer lpMultiByteStr dan lpWideCharStr tidak boleh sama. Jika sama, fungsi gagal, dan GetLastError mengembalikan ERROR_INVALID_PARAMETER.
WideCharToMultiByte tidak mengakhiri string output null jika panjang string input ditentukan secara eksplisit tanpa karakter null yang mengakhiri. Untuk menghentikan string output null untuk fungsi ini, aplikasi harus meneruskan -1 atau secara eksplisit menghitung karakter null yang mengakhiri untuk string input.
Jika cbMultiByte kurang dari cchWideChar, fungsi ini menulis jumlah karakter yang ditentukan oleh cbMultiByte ke buffer yang ditunjukkan oleh lpMultiByteStr. Namun, jika CodePage diatur ke CP_SYMBOL dan cbMultiByte kurang dari cchWideChar, fungsi tidak menulis karakter ke lpMultiByteStr.
Fungsi WideCharToMultiByte beroperasi paling efisien ketika lpDefaultChar dan lpUsedDefaultChar diatur ke NULL. Tabel berikut menunjukkan perilaku fungsi untuk empat kemungkinan kombinasi parameter ini.
| lpDefaultChar | lpUsedDefaultChar | Hasil |
|---|---|---|
| NULL | NULL | Tidak ada pemeriksaan default. Pengaturan parameter ini adalah yang paling efisien untuk digunakan dengan fungsi ini. |
| Karakter non-null | NULL | Menggunakan karakter default yang ditentukan, tetapi tidak mengatur lpUsedDefaultChar. |
| NULL | Karakter non-null | Menggunakan karakter default sistem dan mengatur lpUsedDefaultChar jika perlu. |
| Karakter non-null | Karakter non-null | Menggunakan karakter default yang ditentukan dan mengatur lpUsedDefaultChar jika perlu. |
Dimulai dengan Windows Vista, fungsi ini sepenuhnya sesuai dengan spesifikasi Unicode 4.1 untuk UTF-8 dan UTF-16. Fungsi yang digunakan pada sistem operasi sebelumnya mengodekan atau mendekode bagian pengganti penyendiri atau pasangan pengganti yang tidak cocok. Kode yang ditulis dalam versi Windows sebelumnya yang mengandalkan perilaku ini untuk mengodekan data biner non-teks acak mungkin mengalami masalah. Namun, kode yang menggunakan fungsi ini untuk menghasilkan string UTF-8 yang valid akan berperilaku sama seperti pada sistem operasi Windows sebelumnya.
Dimulai dengan Windows 8: WideCharToMultiByte dideklarasikan dalam Stringapiset.h. Sebelum Windows 8, itu dinyatakan di Winnls.h.
WC_COMPOSITECHECK dan bendera terkait
Seperti yang dibahas dalam Menggunakan Normalisasi Unicode untuk Mewakili String, Unicode memungkinkan beberapa representasi string yang sama (ditafsirkan secara linguistik). Misalnya, Kapital A dengan dieresis (umlaut) dapat direpresentasikan sebagai titik kode Unicode tunggal "Ä" (U+00C4) atau diurai sebagai kombinasi Modal A dan menggabungkan karakter dieresis ("A" + " ̈", yaitu U+0041 U+0308). Namun, sebagian besar halaman kode hanya menyediakan karakter yang terdiri.Bendera WC_COMPOSITECHECK menyebabkan fungsi WideCharToMultiByte menguji karakter Unicode yang diurai dan mencoba menyusunnya sebelum mengonversinya ke halaman kode yang diminta. Bendera ini hanya tersedia untuk konversi ke halaman kode byte tunggal (SBCS) atau byte ganda (DBCS) (halaman < kode 50000, tidak termasuk halaman kode 42). Jika aplikasi Anda perlu mengonversi data Unicode yang diurai ke halaman kode byte tunggal atau byte ganda, bendera ini mungkin berguna. Namun, tidak semua karakter dapat dikonversi dengan cara ini dan lebih dapat diandalkan untuk menyimpan dan menyimpan data seperti Unicode.
Saat aplikasi menggunakan WC_COMPOSITECHECK, beberapa kombinasi karakter mungkin tetap tidak lengkap atau mungkin memiliki karakter nonspacing tambahan yang tersisa. Misalnya, A + ̈ + ̈ digabungkan ke Ä + ̈. Menggunakan bendera WC_DISCARDNS menyebabkan fungsi membuang karakter nonspacing tambahan. Menggunakan bendera WC_DEFAULTCHAR menyebabkan fungsi menggunakan karakter pengganti default (biasanya "?") sebagai gantinya. Menggunakan bendera WC_SEPCHARS menyebabkan fungsi mencoba mengonversi setiap karakter nonspacing tambahan ke halaman kode target. Biasanya bendera ini juga menyebabkan penggunaan karakter pengganti ("?"). Namun, untuk halaman kode 1258 (Vietnam) dan 20269, karakter nonspacing ada dan dapat digunakan. Konversi untuk halaman kode ini tidak sempurna. Beberapa kombinasi tidak dikonversi dengan benar ke halaman kode 1258, dan WC_COMPOSITECHECK merusak data di halaman kode 20269. Seperti disebutkan sebelumnya, lebih dapat diandalkan untuk merancang aplikasi Anda untuk menyimpan dan menyimpan data seperti Unicode.
Contoh
ISDSC_STATUS DiscpUnicodeToAnsiSize(
IN __in PWCHAR UnicodeString,
OUT ULONG *AnsiSizeInBytes
)
/*++
Routine Description:
This routine will return the length needed to represent the unicode
string as ANSI
Arguments:
UnicodeString is the unicode string whose ansi length is returned
*AnsiSizeInBytes is number of bytes needed to represent unicode
string as ANSI
Return Value:
ERROR_SUCCESS or error code
--*/
{
_try
{
*AnsiSizeInBytes = WideCharToMultiByte(CP_ACP,
0,
UnicodeString,
-1,
NULL,
0, NULL, NULL);
} _except(EXCEPTION_EXECUTE_HANDLER) {
return(ERROR_NOACCESS);
}
return((*AnsiSizeInBytes == 0) ? GetLastError() : ERROR_SUCCESS);
}
Persyaratan
| Klien minimum yang didukung | Windows 2000 Professional [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows 2000 Server [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | stringapiset.h (termasuk Windows.h) |
| Pustaka | Kernel32.lib |
| DLL | Kernel32.dll |