Fungsi MultiByteToWideChar (stringapiset.h)
Memetakan string karakter ke string UTF-16 (karakter lebar). String karakter belum tentu dari set karakter multibyte.
Sintaks
int MultiByteToWideChar(
[in] UINT CodePage,
[in] DWORD dwFlags,
[in] _In_NLS_string_(cbMultiByte)LPCCH lpMultiByteStr,
[in] int cbMultiByte,
[out, optional] LPWSTR lpWideCharStr,
[in] int cchWideChar
);
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, dengan MB_PRECOMPOSED menjadi default. MB_PRECOMPOSED dan MB_COMPOSITE saling eksklusif. MB_USEGLYPHCHARS dan MB_ERR_INVALID_CHARS dapat diatur terlepas dari status bendera lainnya.
| Nilai | Makna |
|---|---|
| MB_COMPOSITE | Selalu gunakan 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). Perhatikan bahwa bendera ini tidak dapat digunakan dengan MB_PRECOMPOSED. |
| MB_ERR_INVALID_CHARS | Gagal jika ditemukan karakter input yang tidak valid. Dimulai dengan Windows Vista, fungsi tidak menghilangkan titik kode ilegal jika aplikasi tidak mengatur bendera ini, tetapi mengganti urutan ilegal dengan U+FFFD (dikodekan sesuai untuk halaman kode yang ditentukan). Windows 2000 dengan SP4 dan yang lebih baru, Windows XP: Jika bendera ini tidak diatur, fungsi secara diam-diam menghilangkan titik kode ilegal. Panggilan ke GetLastError mengembalikan ERROR_NO_UNICODE_TRANSLATION. |
- MB_PRECOMPOSED
- MB_USEGLYPHCHARS
Untuk halaman kode yang tercantum di bawah ini, dwFlags harus diatur ke 0. Jika tidak, fungsi gagal dengan ERROR_INVALID_FLAGS.
- 50220
- 50221
- 50222
- 50225
- 50227
- 50229
- 57002 hingga 57011
- 65000 (UTF-7)
- 42 (Simbol)
Catatan
Untuk UTF-8 atau halaman kode 54936 (GB18030, dimulai dengan Windows Vista), dwFlags harus diatur ke salah satu 0 atau MB_ERR_INVALID_CHARS. Jika tidak, fungsi gagal dengan ERROR_INVALID_FLAGS.
[in] lpMultiByteStr
Arahkan ke string karakter untuk dikonversi.
[in] cbMultiByte
Ukuran, dalam byte, dari string yang ditunjukkan oleh parameter lpMultiByteStr . Atau, parameter ini dapat diatur ke -1 jika string dihentikan null. Perhatikan bahwa, jika cbMultiByte adalah 0, fungsi gagal.
Jika parameter ini adalah -1, fungsi memproses seluruh string input, termasuk karakter null yang mengakhiri. Oleh karena itu, string Unicode 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 byte yang ditentukan dengan tepat. Jika ukuran yang disediakan tidak menyertakan karakter null yang mengakhiri, string Unicode yang dihasilkan tidak dihentikan null, dan panjang yang dikembalikan tidak menyertakan karakter ini.
[out, optional] lpWideCharStr
Penunjuk ke buffer yang menerima string yang dikonversi.
[in] cchWideChar
Ukuran, dalam karakter, dari buffer yang ditunjukkan oleh lpWideCharStr. Jika nilai ini adalah 0, fungsi mengembalikan ukuran buffer yang diperlukan, dalam karakter, termasuk karakter null yang mengakhiri, dan tidak menggunakan buffer lpWideCharStr .
Nilai kembali
Mengembalikan jumlah karakter yang ditulis ke buffer yang ditunjukkan oleh lpWideCharStr jika berhasil. Jika fungsi berhasil dan cchWideChar adalah 0, nilai yang dikembalikan adalah ukuran yang diperlukan, dalam karakter, untuk buffer yang ditunjukkan oleh lpWideCharStr. Lihat juga dwFlags untuk informasi tentang bagaimana bendera MB_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 disediakan untuk bendera tidak valid.
- ERROR_INVALID_PARAMETER: Salah satu nilai parameter tidak valid.
- ERROR_NO_UNICODE_TRANSLATION: Unicode tidak valid ditemukan dalam string.
Keterangan
Perilaku default fungsi ini adalah menerjemahkan ke bentuk string karakter input yang telah dikomposisi sebelumnya. Jika formulir yang telah dikomposisi sebelumnya tidak ada, fungsi mencoba menerjemahkan ke formulir komposit.
Penggunaan bendera MB_PRECOMPOSED sangat sedikit berpengaruh pada sebagian besar halaman kode karena sebagian besar data input sudah terdiri. Pertimbangkan untuk memanggil NormalizeString setelah mengonversi dengan MultiByteToWideChar. NormalizeString menyediakan data yang lebih akurat, standar, dan konsisten, dan juga bisa lebih cepat. Perhatikan bahwa untuk enumerasi NORM_FORM diteruskan ke NormalizeString, NormalizationC sesuai dengan MB_PRECOMPOSED dan NormalizationD sesuai dengan MB_COMPOSITE.
Seperti disebutkan dalam peringatan di atas, buffer output dapat dengan mudah diserbu jika fungsi ini tidak pertama kali disebut dengan cchWideChar diatur ke 0 untuk mendapatkan ukuran yang diperlukan. Jika bendera MB_COMPOSITE digunakan, output dapat memiliki panjang tiga karakter atau lebih untuk setiap karakter input.
Pointer lpMultiByteStr dan lpWideCharStr tidak boleh sama. Jika sama, fungsi gagal, dan GetLastError mengembalikan nilai ERROR_INVALID_PARAMETER.
MultiByteToWideChar tidak menghentikan 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.
Fungsi gagal jika MB_ERR_INVALID_CHARS diatur dan karakter yang tidak valid ditemukan dalam string sumber. Karakter yang tidak valid adalah salah satu dari berikut ini:
- Karakter yang bukan karakter default dalam string sumber, tetapi diterjemahkan ke karakter default saat MB_ERR_INVALID_CHARS tidak diatur.
- Untuk string DBCS, karakter yang memiliki byte prospek tetapi tidak ada byte jejak yang valid.
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 penyepian 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 pada string UTF-8 yang valid akan berperilaku sama seperti pada sistem operasi Windows sebelumnya.
Windows XP: Untuk mencegah masalah keamanan versi non-bentuk terpendek dari karakter UTF-8, MultiByteToWideChar menghapus karakter ini.
Dimulai dengan Windows 8:MultiByteToWideChar dinyatakan dalam Stringapiset.h. Sebelum Windows 8, itu dinyatakan dalam Winnls.h.
Contoh kode
catch (std::exception e)
{
// Save in-memory logging buffer to a log file on error.
::std::wstring wideWhat;
if (e.what() != nullptr)
{
int convertResult = MultiByteToWideChar(CP_UTF8, 0, e.what(), (int)strlen(e.what()), NULL, 0);
if (convertResult <= 0)
{
wideWhat = L"Exception occurred: Failure to convert its message text using MultiByteToWideChar: convertResult=";
wideWhat += convertResult.ToString()->Data();
wideWhat += L" GetLastError()=";
wideWhat += GetLastError().ToString()->Data();
}
else
{
wideWhat.resize(convertResult + 10);
convertResult = MultiByteToWideChar(CP_UTF8, 0, e.what(), (int)strlen(e.what()), &wideWhat[0], (int)wideWhat.size());
if (convertResult <= 0)
{
wideWhat = L"Exception occurred: Failure to convert its message text using MultiByteToWideChar: convertResult=";
wideWhat += convertResult.ToString()->Data();
wideWhat += L" GetLastError()=";
wideWhat += GetLastError().ToString()->Data();
}
else
{
wideWhat.insert(0, L"Exception occurred: ");
}
}
}
else
{
wideWhat = L"Exception occurred: Unknown.";
}
Platform::String^ errorMessage = ref new Platform::String(wideWhat.c_str());
// The session added the channel at level Warning. Log the message at
// level Error which is above (more critical than) Warning, which
// means it will actually get logged.
_channel->LogMessage(errorMessage, LoggingLevel::Error);
SaveLogInMemoryToFileAsync().then([=](StorageFile^ logFile) {
_logFileGeneratedCount++;
StatusChanged(this, ref new LoggingScenarioEventArgs(LoggingScenarioEventType::LogFileGenerated, logFile->Path->Data()));
}).wait();
}
Contoh dari Sampel Universal Windows di GitHub.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| 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 |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk