Fungsi RtlUTF8StringToUnicodeString (ntifs.h)

  • Artikel

Rutinitas RtlUTF8StringToUnicodeString mengonversi string UTF-8 yang ditentukan menjadi string Unicode.

Sintaks

NTSYSAPI NTSTATUS RtlUTF8StringToUnicodeString(
  PUNICODE_STRING DestinationString,
  PUTF8_STRING    SourceString,
  BOOLEAN         AllocateDestinationString
);

Parameter

DestinationString

Penunjuk ke buffer tempat string Unicode output yang dikonversi disimpan. Bidang DestinationString-MaximumLength> diatur hanya jika AllocateDestinationString ADALAH TRUE.

SourceString

Penunjuk ke string sumber UTF-8 untuk dikonversi ke Unicode.

AllocateDestinationString

Nilai boolean. Ketika diatur TRUE, RtlUTF8StringToUnicodeString mengalokasikan ruang buffer untuk string tujuan. Hanya penyimpanan untuk DestinationString-Buffer> yang dialokasikan oleh API ini. Jika RtlUTF8StringToUnicodeString melakukan alokasi buffer, maka pemanggil harus membatalkan alokasi buffer menggunakan RtlFreeUnicodeString.

Nilai kembali

Fungsi ini mengembalikan STATUS_SUCCESS ketika konversi berhasil. Kemungkinan kesalahan atau kode peringatan meliputi:

Kode Deskripsi
STATUS_INVALID_PARAMETERX Kesalahan: Salah satu nilai parameter tidak valid.
STATUS_NO_MEMORY Kesalahan: RtlUTF8StringToUnicodeString tidak dapat mengalokasikan ruang buffer.
STATUS_BUFFER_OVERFLOW Peringatan: String yang dikonversi di DestinationString-Buffer> dipotok karena ruang yang tidak mencukup di buffer tujuan.
STATUS_SOME_NOT_MAPPED Peringatan: Panggilan berhasil, tetapi satu atau beberapa karakter input tidak valid dan dikonversi oleh karakter pengganti Unicode, U+FFFD, sebelum dikonversi ke UTF-8.

Keterangan

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

RtlUTF8StringToUnicodeString 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.

RtlUTF8StringToUnicodeString terus mengonversi string input menjadi string output hingga mencapai akhir buffer sumber atau akhir buffer tujuan, mana pun 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 RtlUnicodeStringToUTF8String mengonversi string Unicode menjadi string UTF-8.

Anda dapat menggunakan rutinitas RtlUTF8StringToUnicodeString dan RtlUnicodeStringToUTF8String 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 Windows 10, version 2004
Target Platform Universal
Header ntifs.h (termasuk Ntifs.h, Wdm.h, Ntifs.h)
Pustaka NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

Lihat juga

RtlFreeUnicodeString

RtlUnicodeStringToUTF8String