Fungsi RtlUnicodeToUTF8N (wdm.h)

  • Artikel

Rutinitas RtlUnicodeToUTF8N mengonversi string Unicode menjadi string UTF-8.

Sintaks

NTSYSAPI NTSTATUS RtlUnicodeToUTF8N(
  [out] PCHAR  UTF8StringDestination,
  [in]  ULONG  UTF8StringMaxByteCount,
  [out] PULONG UTF8StringActualByteCount,
  [in]  PCWCH  UnicodeStringSource,
  [in]  ULONG  UnicodeStringByteCount
);

Parameter

[out] UTF8StringDestination

Penunjuk ke buffer tujuan yang dialokasikan penelepon tempat rutin menulis string output UTF-8. Jika parameter ini NULL, rutin menulis ukuran buffer output yang diperlukan ke *UTF8StringActualByteCount.

[in] UTF8StringMaxByteCount

Menentukan jumlah maksimum byte yang dapat ditulis rutin ke buffer yang dituju oleh UTF8StringDestination . Jika UTF8StringDestination = NULL, atur UTF8StringMaxByteCount = 0.

[out] UTF8StringActualByteCount

Pointer ke lokasi di mana rutinitas menulis jumlah byte aktual yang telah ditulisnya ke buffer yang dituju oleh UTF8StringDestination . Jika UTF8StringDestinationnon-NULL, jumlah ini tidak pernah melebihi nilai UTF8StringMaxByteCount. Jika UTF8StringDestination adalah NULL, jumlah ini adalah jumlah byte yang diperlukan untuk berisi seluruh string output.

[in] UnicodeStringSource

Penunjuk ke string sumber Unicode.

[in] UnicodeStringByteCount

Menentukan jumlah byte dalam string sumber Unicode yang dituju oleh parameter UnicodeStringSource .

Nilai kembali

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

Menampilkan kode Deskripsi
STATUS_BUFFER_TOO_SMALL
 Parameter UTF8StringMaxByteCount menentukan ukuran buffer yang terlalu kecil untuk berisi seluruh string output.
STATUS_INVALID_PARAMETER
 Parameter UTF8StringDestination dan UTF8StringActualByteCount keduanya ADALAH NULL.
STATUS_INVALID_PARAMETER_4
 Parameter UnicodeStringSource adalah NULL.
STATUS_INVALID_PARAMETER_5
 UnicodeStringByteCount bukan kelipatan bilangan bulat dari sizeof(WCHAR).

Keterangan

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

Rutinitas mengembalikan STATUS_BUFFER_TOO_SMALL jika parameter UTF8StringMaxByteCount menentukan ukuran buffer yang terlalu kecil untuk berisi seluruh string output. Dalam hal ini, rutin menulis sebanyak karakter UTF-8 seperti yang akan muat dalam buffer, dan nilai *UTF8StringActualByteCount 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 RtlUnicodeToUTF8N untuk mendapatkan ukuran buffer output yang diperlukan, lalu memanggil RtlUnicodeToUTF8N lagi untuk mendapatkan string output Unicode. Dalam panggilan awal, atur UTF8StringDestination = NULL dan UTF8StringMaxByteCount = 0, dan rutinitas akan menulis ukuran buffer yang diperlukan ke *UTF8StringActualByteCount. Selanjutnya, alokasikan buffer dengan ukuran yang diperlukan dan panggil RtlUnicodeToUTF8N untuk kedua kalinya untuk mendapatkan string output UTF-8.

RtlUnicodeToUTF8N 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 kode karakter yang valid dan digantikan oleh karakter pengganti Unicode, U+FFFD.

RtlUnicodeToUTF8N 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 RtlUTF8ToUnicodeN mengonversi string UTF-8 menjadi string Unicode.

Anda dapat menggunakan rutinitas RtlUnicodeToUTF8N dan RtlUTF8ToUnicode untuk melakukan konversi tanpa kehilangan string teks yang valid antara format Unicode dan UTF-8. 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

RtlUTF8ToUnicodeN