Fungsi RtlUTF8ToUnicodeN (ntifs.h)

Rutinitas RtlUTF8ToUnicodeN mengonversi string UTF-8 menjadi string Unicode.

NTSYSAPI NTSTATUS RtlUTF8ToUnicodeN(
  [out, optional] PWSTR  UnicodeStringDestination,
  [in]            ULONG  UnicodeStringMaxByteCount,
  [out]           PULONG UnicodeStringActualByteCount,
  [in]            PCCH   UTF8StringSource,
  [in]            ULONG  UTF8StringByteCount
);

[out, optional] UnicodeStringDestination

Penunjuk ke buffer tujuan yang dialokasikan pemanggil tempat rutin menulis string output Unicode. Jika parameter ini null, rutin menulis ukuran buffer output yang diperlukan ke *UnicodeStringActualByteCount.

[in] UnicodeStringMaxByteCount

Menentukan jumlah maksimum byte yang dapat ditulis rutinitas ke buffer yang UnicodeStringDestination menunjuk. Jika UnicodeStringDestination = NULL, atur UnicodeStringMaxByteCount = 0.

[out] UnicodeStringActualByteCount

Penunjuk ke lokasi tempat rutin menulis jumlah byte aktual yang telah ditulis rutinitas ke buffer yang UnicodeStringDestination menunjuk. Jika UnicodeStringDestination non-NULL, jumlah ini tidak pernah melebihi nilai UnicodeStringMaxByteCount. Jika UnicodeStringDestinationNULL, jumlah ini adalah jumlah byte yang diperlukan untuk berisi seluruh string output.

[in] UTF8StringSource

Penunjuk ke string sumber UTF-8.

[in] UTF8StringByteCount

Menentukan jumlah byte dalam string sumber UTF-8 yang ditujukan parameter UTF8StringSource.

RtlUTF8ToUnicodeN mengembalikan STATUS_SUCCESS jika panggilan berhasil dan semua kode karakter UTF-8 dalam string input dikonversi ke kode karakter Unicode yang sesuai dalam string output. Ini mengembalikan STATUS_SOME_NOT_MAPPED jika panggilan berhasil tetapi satu atau beberapa karakter input tidak valid dan dikonversi ke karakter pengganti Unicode, U+FFFD. Kemungkinan nilai pengembalian kesalahan menyertakan kode kesalahan berikut:

String output Unicode dihentikan null hanya jika string input UTF-8 dihentikan null.

Rutinitas mengembalikan STATUS_BUFFER_TOO_SMALL jika parameter UnicodeStringMaxByteCount menentukan ukuran buffer yang terlalu kecil untuk berisi seluruh string output. Dalam hal ini, rutin menulis karakter Unicode sebanyak yang akan muat dalam buffer, dan nilai *UnicodeStringActualByteCount menentukan jumlah byte valid yang telah ditulis rutinitas ke buffer. String parsial yang terkandung dalam buffer output mungkin tidak menyertakan karakter null yang mengakhiri.

Anda dapat melakukan panggilan awal ke RtlUTF8ToUnicodeN untuk mendapatkan ukuran buffer output yang diperlukan, lalu memanggil RtlUTF8ToUnicodeN lagi untuk mendapatkan string output Unicode. Dalam panggilan awal, atur UnicodeStringDestination = null dan UnicodeStringMaxByteCount = 0, dan rutinitas akan menulis ukuran buffer yang diperlukan ke *UnicodeStringActualByteCount. Selanjutnya, alokasikan buffer dengan ukuran yang diperlukan dan panggil RtlUTF8ToUnicodeN kedua kalinya untuk mendapatkan string output Unicode.

RtlUTF8ToUnicodeN mendukung pasangan pengganti Unicode. Namun, nilai kata depan pengganti yang tidak diikuti oleh nilai kata berikutnya, atau nilai kata berikutnya yang tidak didahului oleh nilai kata di depan, tidak dikenali sebagai karakter yang valid dan digantikan oleh karakter pengganti Unicode, U+FFFD.

RtlUTF8ToUnicodeN terus mengonversi string input ke string output hingga mencapai akhir buffer sumber atau akhir buffer tujuan, mana yang terjadi terlebih dahulu. Rutinitas mengonversi karakter null dalam string input menjadi karakter null dalam string output. Jika string input berisi karakter null yang mengakhiri, tetapi karakter null tidak terletak di akhir buffer sumber, rutinitas terus melewati karakter null yang mengakhiri hingga mencapai akhir ruang buffer yang tersedia.

Rutinitas RtlUnicodeToUTF8N mengonversi string Unicode menjadi string UTF-8.

Anda dapat menggunakan RtlUTF8ToUnicodeN dan RtlUnicodeToUTF8N rutinitas untuk melakukan konversi string teks yang valid tanpa kerugian antara format UTF-8 dan Unicode. Namun, string yang memiliki nilai data arbitrer kemungkinan melanggar aturan Unicode untuk mengodekan pasangan pengganti, dan informasi apa pun yang terkandung dalam nilai yang tidak valid dalam string input hilang dan tidak dapat dipulihkan dari string output yang dihasilkan.

RtlUnicodeToUTF8N