Fungsi MultiByteToWideChar (stringapiset.h)

Artikel
07/16/2024

Memetakan string karakter ke string UTF-16 (karakter lebar). String karakter belum tentu dari set karakter multibyte.

Hati-hati Menggunakan fungsi MultiByteToWideChar salah dapat membahayakan keamanan aplikasi Anda. Memanggil fungsi ini dapat dengan mudah menyebabkan buffer diserbu karena ukuran buffer input yang ditunjukkan oleh lpMultiByteStr sama dengan jumlah byte dalam string, sementara ukuran buffer output yang ditunjukkan oleh lpWideCharStr sama dengan jumlah karakter. Untuk menghindari overrun buffer, aplikasi Anda harus menentukan ukuran buffer yang sesuai untuk jenis data yang diterima buffer. Untuk informasi selengkapnya, lihat Pertimbangan Keamanan : Fitur Internasional.

Catatan Halaman kode ANSI dapat berbeda di komputer yang berbeda, atau dapat diubah untuk satu komputer, yang mengarah ke kerusakan data. Untuk hasil yang paling konsisten, aplikasi harus menggunakan Unicode, seperti UTF-8 atau UTF-16, alih-alih halaman kode tertentu, kecuali standar warisan atau format data mencegah penggunaan Unicode. Jika menggunakan Unicode tidak dimungkinkan, aplikasi harus menandai aliran data dengan nama pengodean yang sesuai saat protokol mengizinkannya. File HTML dan XML mengizinkan pemberian tag, tetapi file teks tidak.

Sintaksis

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 yang akan 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 ditampilkan dalam tabel berikut.

Nilai	Arti
CP_ACP	Halaman kode WINDOWS ANSI default sistem. Catatan Nilai ini bisa berbeda di komputer yang berbeda, bahkan pada jaringan yang sama. Ini dapat diubah pada komputer yang sama, yang menyebabkan data tersimpan menjadi rusak secara tidak dapat dipulihkan. Nilai ini hanya ditujukan untuk penggunaan sementara dan penyimpanan permanen harus menggunakan UTF-16 atau UTF-8 jika memungkinkan.
CP_MACCP	Halaman kode Macintosh sistem saat ini. Catatan Nilai ini bisa berbeda di komputer yang berbeda, bahkan pada jaringan yang sama. Ini dapat diubah pada komputer yang sama, yang menyebabkan data tersimpan menjadi rusak secara tidak dapat dipulihkan. Nilai ini hanya ditujukan untuk penggunaan sementara dan penyimpanan permanen harus menggunakan UTF-16 atau UTF-8 jika memungkinkan. Catatan Nilai ini digunakan terutama dalam kode warisan dan umumnya tidak boleh diperlukan karena komputer Macintosh modern menggunakan Unicode untuk pengodean.
CP_OEMCP	Halaman kode OEM sistem saat ini. Catatan Nilai ini bisa berbeda di komputer yang berbeda, bahkan pada jaringan yang sama. Ini dapat diubah pada komputer yang sama, yang menyebabkan data tersimpan menjadi rusak secara tidak dapat dipulihkan. Nilai ini hanya ditujukan untuk penggunaan sementara dan penyimpanan permanen harus menggunakan UTF-16 atau UTF-8 jika memungkinkan.
CP_SYMBOL	Halaman kode simbol (42).
CP_THREAD_ACP	Halaman kode Ansi Windows untuk utas saat ini. Catatan Nilai ini bisa berbeda di komputer yang berbeda, bahkan pada jaringan yang sama. Ini dapat diubah pada komputer yang sama, yang menyebabkan data tersimpan menjadi rusak secara tidak dapat dipulihkan. Nilai ini hanya ditujukan untuk penggunaan sementara dan penyimpanan permanen harus menggunakan UTF-16 atau UTF-8 jika memungkinkan.
CP_UTF7	UTF-7. Gunakan nilai ini hanya jika dipaksa oleh mekanisme transportasi 7-bit. Penggunaan UTF-8 lebih disukai.
CP_UTF8	UTF-8.

[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	Arti
MB_COMPOSITE	Selalu gunakan karakter yang didekomposisikan, 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 KAPITAL LATIN A (U+0041) + MENGGABUNGKAN DIAERESIS (U+0308). Perhatikan bahwa bendera ini tidak dapat digunakan dengan MB_PRECOMPOSED.
MB_ERR_INVALID_CHARS	Gagal jika karakter input tidak valid ditemui. 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.

Nilai

Arti

MB_COMPOSITE

Selalu gunakan karakter yang didekomposisikan, 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 KAPITAL LATIN A (U+0041) + MENGGABUNGKAN DIAERESIS (U+0308). Perhatikan bahwa bendera ini tidak dapat digunakan dengan MB_PRECOMPOSED.

MB_ERR_INVALID_CHARS

Gagal jika karakter input tidak valid ditemui.

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

Default; jangan gunakan dengan MB_COMPOSITE. Selalu gunakan karakter yang telah dikomposisikan sebelumnya, yaitu karakter yang memiliki nilai karakter tunggal untuk kombinasi karakter dasar atau nonspacing. Misalnya, dalam karakter è, e adalah karakter dasar dan tanda kubur aksen adalah karakter nonspacing. Jika satu titik kode Unicode didefinisikan untuk karakter, aplikasi harus menggunakannya alih-alih karakter dasar terpisah dan karakter nonspacing. Misalnya, Ä diwakili oleh titik kode Unicode tunggal LATIN CAPITAL LETTER A WITH DIAERESIS (U+00C4).

MB_USEGLYPHCHARS

Gunakan karakter glyph alih-alih karakter kontrol.

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)

Nota

Untuk halaman UTF-8 atau kode 54936 (GB18030, dimulai dengan Windows Vista), dwFlags harus diatur ke 0 atau MB_ERR_INVALID_CHARS. Jika tidak, fungsi gagal dengan ERROR_INVALID_FLAGS.

[in] lpMultiByteStr

Penunjuk 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 cbMultiByte0, 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 dihentikan, dan panjang yang dikembalikan oleh fungsi mencakup karakter ini.

Jika parameter ini diatur ke bilangan bulat positif, fungsi memproses jumlah byte yang ditentukan. Jika ukuran yang disediakan tidak menyertakan karakter null yang dihentikan, 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 0, fungsi mengembalikan ukuran buffer yang diperlukan, dalam karakter, termasuk karakter null yang mengakhiri, dan tidak menggunakan lpWideCharStr buffer.

Mengembalikan nilai

Mengembalikan jumlah karakter yang ditulis ke buffer yang ditunjukkan oleh lpWideCharStr jika berhasil. Jika fungsi berhasil dan cchWideChar 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 pengembalian 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.

Komentar

Perilaku default fungsi ini adalah menerjemahkan ke bentuk string karakter input yang telah diolah sebelumnya. Jika formulir yang telah dikomposisikan sebelumnya tidak ada, fungsi mencoba menerjemahkan ke bentuk 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 denganMultiByteToWideChar . 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 NormalisasiD sesuai dengan MB_COMPOSITE.

Seperti disebutkan dalam peringatan di atas, buffer output dapat dengan mudah diserbu jika fungsi ini tidak pertama kali dipanggil 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 mengakhiri string output null jika panjang string input ditentukan secara eksplisit tanpa mengakhiri karakter null. Untuk menghentikan string output null untuk fungsi ini, aplikasi harus meneruskan -1 atau secara eksplisit menghitung karakter null penghentian 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 lone pengganti bagian 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 karakter UTF-8, MultiByteToWideChar menghapus karakter ini.

Dimulai dengan Windows 8: MultiByteToWideChar dideklarasikan 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

Syarat	Nilai
klien minimum yang didukung	Windows 2000 Professional [aplikasi desktop \| Aplikasi UWP]
server minimum yang didukung	Windows 2000 Server [aplikasi desktop \| Aplikasi UWP]
Platform Target	Windows
Header	stringapiset.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

Fungsi Unicode dan Set Karakter

Unicode dan Set Karakter

WideCharToMultiByte

Vertdll API tersedia di enklave VBS

Bagikan melalui