Fungsi RtlUnicodeStringToUTF8String (ntifs.h)
RtlUnicodeStringToUTF8String mengonversi string Unicode yang ditentukan menjadi string UTF-8.
Sintaks
NTSYSAPI NTSTATUS RtlUnicodeStringToUTF8String(
PUTF8_STRING DestinationString,
PCUNICODE_STRING SourceString,
BOOLEAN AllocateDestinationString
);
Parameter
DestinationString
Penunjuk ke buffer tempat string UTF-8 output yang dikonversi ditempatkan. Bidang DestinationString-MaximumLength> diatur hanya jika AllocateDestinationString TRUE.
SourceString
Penunjuk ke string Unicode untuk dikonversi ke UTF-8.
AllocateDestinationString
Nilai boolean. Saat diatur TRUE, RtlUnicodeStringToUTF8String mengalokasikan ruang buffer untuk string tujuan. Hanya penyimpanan untuk DestinationString-Buffer> yang dialokasikan oleh API ini. Jika RtlUnicodeStringToUTF8String melakukan alokasi buffer, maka pemanggil harus membatalkan alokasi buffer menggunakan RtlFreeUTF8String.
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: RtlUnicodeStringToUTF8String tidak dapat mengalokasikan ruang buffer. |
| STATUS_BUFFER_OVERFLOW | Peringatan: String yang dikonversi di DestinationString-Buffer> dipotong karena ruang yang tidak mencukup di buffer tujuan. |
| STATUS_SOME_NOT_MAPPED | Peringatan: Panggilan berhasil, tetapi satu atau beberapa karakter input tidak valid dan digantikan oleh karakter pengganti Unicode, U+FFFD, sebelum dikonversi ke UTF-8. |
Keterangan
String output UTF-8 dihentikan null hanya jika string input Unicode dihentikan null.
RtlUnicodeStringToUTF8String 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.
RtlUnicodeStringToUTF8String 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 RtlUTF8StringToUnicodeString mengonversi string UTF-8 menjadi string Unicode.
Anda dapat menggunakan rutinitas RtlUnicodeStringToUTF8String dan RtlUTF8StringToUnicodeString untuk melakukan konversi string teks yang valid tanpa kerugian antara format Unicode dan UTF-8. Namun, string yang memiliki nilai data arbitrer kemungkinan melanggar aturan Unicode untuk pengodean 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 |
| Header | ntifs.h |