Fungsi RtlUTF8ToUnicodeN (wdm.h)

Artikel
08/03/2023

Rutinitas RtlUTF8ToUnicodeN mengonversi string UTF-8 menjadi string Unicode.

Sintaks

C++

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

Parameter

[out, optional] UnicodeStringDestination

Penunjuk ke buffer tujuan yang dialokasikan penelepon 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 rutin ke buffer yang dituju unicodeStringDestination . Jika UnicodeStringDestination = NULL, atur UnicodeStringMaxByteCount = 0.

[out] UnicodeStringActualByteCount

Penunjuk ke lokasi di mana rutinitas menulis jumlah byte aktual yang telah ditulis rutinitas ke buffer yang dituju UnicodeStringDestination . Jika UnicodeStringDestination bukan NULL, jumlah ini tidak pernah melebihi nilai UnicodeStringMaxByteCount. Jika UnicodeStringDestination adalah NULL, 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 dituju oleh parameter UTF8StringSource .

Nilai kembali

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 mencakup kode kesalahan berikut:

Menampilkan kode	Deskripsi
STATUS_BUFFER_TOO_SMALL	Parameter UnicodeStringMaxByteCount menentukan ukuran buffer yang terlalu kecil untuk berisi seluruh string output.
STATUS_INVALID_PARAMETER	Parameter UnicodeStringDestination dan UnicodeStringActualByteCount keduanya adalah NULL.
STATUS_INVALID_PARAMETER_4	Parameter UTF8StringSource adalah NULL.

Keterangan

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 yang 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 untuk 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 menjadi string output hingga mencapai akhir buffer sumber atau akhir buffer tujuan, mana yang terjadi terlebih dahulu. Rutinitas mengonversi karakter null apa pun 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 rutinitas RtlUTF8ToUnicode dan RtlUnicodeToUTF8N untuk melakukan konversi tanpa kehilangan string teks yang valid 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.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Windows 7 dan versi Windows yang lebih baru.
Target Platform	Universal
Header	wdm.h (termasuk Ntifs.h, Wdm.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

Lihat juga

RtlUnicodeToUTF8N

Bagikan melalui