Fungsi RtlUnicodeStringVPrintfEx (ntstrsafe.h)

Artikel
05/03/2024

Fungsi RtlUnicodeStringVPrintfEx membuat string teks, dengan pemformatan yang didasarkan pada informasi pemformatan yang disediakan, dan menyimpan string dalam struktur UNICODE_STRING .

Sintaks

NTSTRSAFEDDI RtlUnicodeStringVPrintfEx(
  [out]           PUNICODE_STRING  DestinationString,
  [out, optional] PUNICODE_STRING  RemainingString,
  [in]            DWORD            dwFlags,
  [in]            NTSTRSAFE_PCWSTR pszFormat,
  [in]            va_list          argList
);

Parameter

[out] DestinationString

Pilihan. Penunjuk ke struktur UNICODE_STRING yang menerima string yang diformat. RtlUnicodeStringVPrintfEx membuat string ini dari string pemformatan yang disediakan pszFormat dan daftar argumen fungsi. Jumlah maksimum karakter dalam string adalah NTSTRSAFE_UNICODE_STRING_MAX_CCH. DestinationString bisa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.

[out, optional] RemainingString

Pilihan. Jika pemanggil menyediakan penunjuk non-NULL ke struktur UNICODE_STRING , RtlUnicodeStringVPrintfE mengatur anggota Buffer struktur ini ke akhir string yang diformat, mengatur anggota Panjang struktur ke nol, dan mengatur anggota MaximumLength struktur ke jumlah byte yang tersisa di buffer tujuan. RemainingString bisa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.

[in] dwFlags

Satu atau beberapa bendera dan, secara opsional, byte isian. Bendera didefinisikan sebagai berikut:

STRSAFE_FILL_BEHIND

Jika bendera ini diatur dan fungsi berhasil, byte rendah dwFlags digunakan untuk mengisi bagian buffer tujuan yang mengikuti karakter terakhir dalam string.

STRSAFE_IGNORE_NULLS

Jika bendera ini diatur, penunjuk sumber atau tujuan, atau keduanya, bisa NULL. RtlUnicodeStringVPrintfEx memperlakukan penunjuk buffer sumber NULL seperti string kosong (TEXT("")), yang dapat disalin. Penunjuk buffer tujuan NULL tidak dapat menerima string yang tidak kosong.

STRSAFE_FILL_ON_FAILURE

Jika bendera ini diatur dan fungsi gagal, byte rendah dwFlags digunakan untuk mengisi seluruh buffer tujuan. Operasi ini menimpa isi buffer yang sudah ada sebelumnya.

STRSAFE_NULL_ON_FAILURE

Jika bendera ini diatur dan fungsi gagal, buffer tujuan diatur ke string kosong (TEXT("")). Operasi ini menimpa isi buffer yang sudah ada sebelumnya.

STRSAFE_NO_TRUNCATION

Jika bendera ini diatur dan fungsi mengembalikan STATUS_BUFFER_OVERFLOW, konten buffer tujuan tidak dimodifikasi.

STRSAFE_ZERO_LENGTH_ON_FAILURE

Jika bendera ini diatur dan fungsi mengembalikan STATUS_BUFFER_OVERFLOW, panjang string tujuan diatur ke nol byte.

[in] pszFormat

Penunjuk ke string teks yang dihentikan nul yang berisi direktif pemformatan bergaya printf. Pointer ini bisa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.

[in] argList

Daftar argumen va_list-ketik. Argumen dalam daftar argumen ini akan ditafsirkan dengan menggunakan string pemformatan yang disediakan pszFormat .

Nilai kembali

RtlUnicodeStringVPrintfEx mengembalikan salah satu nilai NTSTATUS berikut.

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Status keberhasilan ini berarti data sumber ada, dan string digabungkan tanpa pemotongan.
STATUS_BUFFER_OVERFLOW	Status peringatan ini berarti operasi penyalinan tidak selesai karena ruang yang tidak mencukupi di buffer tujuan. Jika STRSAFE_NO_TRUNCATION diatur dalam dwFlags, buffer tujuan tidak dimodifikasi. Jika bendera tidak diatur, buffer tujuan berisi versi terpotong dari string yang disalin.
STATUS_INVALID_PARAMETER	Status kesalahan ini berarti fungsi menerima parameter input yang tidak valid. Untuk informasi selengkapnya, lihat paragraf berikut ini.

RtlUnicodeStringVPrintfEx mengembalikan nilai STATUS_INVALID_PARAMETER ketika salah satu hal berikut ini terjadi:

Isi struktur UNICODE_STRING tidak valid.
Bendera yang tidak valid ditentukan dalam dwFlags.
Buffer tujuan sudah penuh.
Penunjuk buffer adalah NULL dan bendera STRSAFE_IGNORE_NULLS tidak ditentukan dalam dwFlags.
Penunjuk buffer tujuan ADALAH NULL, tetapi ukuran buffer bukan nol.
Penunjuk buffer tujuan adalah NULL, atau panjangnya nol, tetapi string sumber panjang bukan nol ada.

Untuk informasi tentang cara menguji nilai NTSTATUS, lihat Menggunakan Nilai NTSTATUS.

Keterangan

Fungsi RtlUnicodeStringVPrintfEx menggunakan ukuran buffer tujuan untuk memastikan bahwa operasi pemformatan string tidak menulis melewati akhir buffer. Secara default, fungsi tidak mengakhiri string yang dihasilkan dengan nilai karakter null (yaitu, dengan nol). Sebagai opsi, pemanggil dapat menggunakan bendera STRSAFE_FILL_BEHIND dan nilai byte isi nol untuk menghentikan string yang dihasilkan null yang tidak menempati seluruh buffer tujuan.

RtlUnicodeStringVPrintfEx menambahkan fungsionalitas fungsi RtlUnicodeStringVPrintf dengan mengembalikan struktur UNICODE_STRING yang mengidentifikasi akhir string tujuan dan jumlah byte yang dibiarkan tidak digunakan dalam string tersebut. Anda dapat meneruskan bendera ke RtlUnicodeStringVPrintfEx untuk kontrol tambahan.

Jika string format dan string tujuan tumpang tindih, perilaku fungsi tidak ditentukan.

Penunjuk pszFormat dan DestinationString tidak boleh NULL kecuali bendera STRSAFE_IGNORE_NULLS diatur dalam dwFlags. Jika STRSAFE_IGNORE_NULLS diatur, salah satu atau kedua penunjuk ini dapat berupa NULL. Jika penunjuk DestinationStringADALAH NULL, penunjuk pszFormat harus NULL atau mengarah ke string kosong.

Untuk informasi selengkapnya tentang daftar argumen va_list-typed, lihat dokumentasi Microsoft Windows SDK.

Untuk informasi selengkapnya tentang fungsi string aman, lihat Menggunakan Fungsi String Aman.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows XP dengan Paket Layanan 1 (SP1).
Target Platform	Desktop
Header	ntstrsafe.h (termasuk Ntstrsafe.h)
Pustaka	Ntstrsafe.lib
IRQL	Bagaimanapun, jika string yang dimanipulasi selalu berada dalam memori, jika tidak, PASSIVE_LEVEL