Fungsi RtlStringCbVPrintfExA (ntstrsafe.h)

Fungsi RtlStringCbVPrintfExW dan RtlStringCbVPrintfExA membuat string teks yang dihitung byte, dengan pemformatan yang didasarkan pada informasi pemformatan yang disediakan.

Sintaks

NTSTRSAFEDDI RtlStringCbVPrintfExA(
  [out, optional] NTSTRSAFE_PSTR  pszDest,
  [in]            size_t          cbDest,
  [out, optional] NTSTRSAFE_PSTR  *ppszDestEnd,
  [out, optional] size_t          *pcbRemaining,
  [in]            DWORD           dwFlags,
  [in, optional]  NTSTRSAFE_PCSTR pszFormat,
  [in]            va_list         argList
);

Parameter

[out, optional] pszDest

Penunjuk ke buffer yang disediakan penelepon yang menerima string yang diformat dan dihentikan null. Fungsi ini membuat string ini dari string pemformatan yang disediakan oleh pszFormat dan argumen yang disediakan oleh argList. Pointer pszDest bisa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.

[in] cbDest

Ukuran buffer tujuan, dalam byte. Buffer harus cukup besar untuk berisi string yang diformat ditambah karakter null yang mengakhiri.

Untuk string Unicode, jumlah maksimum byte adalah NTSTRSAFE_MAX_CCH * sizeof(WCHAR).

Untuk string ANSI, jumlah maksimum byte adalah NTSTRSAFE_MAX_CCH * sizeof(char).

Jika pszDest adalah NULL, cbDest harus nol.

[out, optional] ppszDestEnd

Jika penelepon menyediakan penunjuk alamat non-NULL , setelah operasi selesai, fungsi memuat alamat tersebut dengan penunjuk ke terminator string null yang dihasilkan buffer tujuan.

[out, optional] pcbRemaining

Jika penelepon memasok penunjuk alamat non-NULL , fungsi memuat alamat dengan jumlah byte yang tidak digunakan yang ada di buffer yang diarahkan oleh pszDest, termasuk byte yang digunakan untuk karakter null yang mengakhiri.

[in] dwFlags

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

Nilai Makna
STRSAFE_FILL_BEHIND_NULL
Jika diatur dan fungsi berhasil, byte rendah dwFlags digunakan untuk mengisi bagian buffer tujuan yang mengikuti karakter null yang mengakhiri.
STRSAFE_IGNORE_NULLS
Jika diatur, pszDest atau pszSrc, atau keduanya, bisa NULL. Pointer pszSrcNULL diperlakukan seperti string kosong (TEXT("")), yang dapat disalin. Pointer pszDestNULL tidak dapat menerima string yang tidak kosong.
STRSAFE_FILL_ON_FAILURE
Jika diatur dan fungsi gagal, byte rendah dwFlags digunakan untuk mengisi seluruh buffer tujuan, dan buffer dihentikan null. Operasi ini menimpa isi buffer yang sudah ada sebelumnya.
STRSAFE_NULL_ON_FAILURE
Jika diatur dan fungsi gagal, buffer tujuan diatur ke string kosong (TEXT("")). Operasi ini menimpa isi buffer yang sudah ada sebelumnya.
STRSAFE_NO_TRUNCATION
Jika diatur dan fungsi mengembalikan STATUS_BUFFER_OVERFLOW, konten buffer tujuan tidak dimodifikasi.

[in, optional] pszFormat

Penunjuk ke string teks null-terminated yang berisi direktif pemformatan bergaya printf. Penunjuk pszFormat dapat berupa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.

[in] argList

Daftar argumen yang ditik va_list. Argumen yang terkandung dalam daftar argumen akan ditafsirkan dengan menggunakan string pemformatan yang disediakan oleh pszFormat.

Mengembalikan nilai

Fungsi mengembalikan salah satu nilai NTSTATUS yang tercantum dalam tabel berikut. Untuk informasi tentang cara menguji nilai NTSTATUS, lihat Menggunakan Nilai NTSTATUS.

Menampilkan kode Deskripsi
STATUS_SUCCESS
Status keberhasilan ini berarti data sumber ada, string output dibuat tanpa pemotokan, dan buffer tujuan yang dihasilkan dihentikan null.
STATUS_BUFFER_OVERFLOW
Status peringatan ini berarti operasi tidak selesai karena ruang yang tidak cukup di buffer tujuan. Jika STRSAFE_NO_TRUNCATION diatur dalam dwFlags, buffer tujuan tidak dimodifikasi. Jika bendera tidak diatur, buffer tujuan berisi versi string yang dibuat yang terpotok.
STATUS_INVALID_PARAMETER
Status kesalahan ini berarti fungsi menerima parameter input yang tidak valid. Untuk informasi selengkapnya, lihat paragraf berikut ini.

Fungsi mengembalikan nilai STATUS_INVALID_PARAMETER saat:

  • Bendera yang tidak valid ditentukan.
  • Nilai dalam cbDest lebih besar dari ukuran buffer maksimum.
  • Buffer tujuan sudah penuh.
  • Penunjuk NULL ada tanpa bendera STRSAFE_IGNORE_NULLS.
  • 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.

Keterangan

RtlStringCbVPrintfExW dan RtlStringCbVPrintfExA harus digunakan alih-alih fungsi berikut:

  • vsprintf
  • vswprintf
  • _vsnprintf
  • _vsnwprintf
Semua fungsi ini menerima string format, bersama dengan sekumpulan argumen dalam daftar argumen yang ditik va_list, dan mengembalikan string yang diformat. Ukuran, dalam byte, dari buffer tujuan disediakan untuk RtlStringCbVPrintfExW dan RtlStringCbVPrintfExA untuk memastikan bahwa mereka tidak menulis melewati akhir buffer.

RtlStringCbVPrintfExW dan RtlStringCbVPrintfExA menambahkan ke fungsionalitas RtlStringCbVPrintf dengan mengembalikan pointer ke akhir string tujuan, serta jumlah byte yang tersisa tidak digunakan dalam string tersebut. Bendera dapat diteruskan ke fungsi untuk kontrol tambahan.

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

Gunakan RtlStringCbVPrintfExW untuk menangani string Unicode dan RtlStringCbVPrintfExA untuk menangani string ANSI. Formulir yang Anda gunakan bergantung pada data Anda, seperti yang diperlihatkan dalam tabel berikut ini.

Jenis data string String literal Fungsi
WCHAR L"string" RtlStringCbVPrintfExW
char "string" RtlStringCbVPrintfExA
 

Jika pszDest dan pszFormat menunjuk ke string yang tumpang tindih, atau jika ada string argumen yang tumpang tindih, perilaku fungsi tidak terdefinisi.

Baik pszFormat maupun pszDest tidak dapat berupa NULL kecuali bendera STRSAFE_IGNORE_NULLS diatur, dalam hal ini baik atau keduanya dapat null. Jika pszDest adalah NULL, pszFormat harus NULL atau menunjuk ke string kosong.

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

Persyaratan

   
Klien minimum yang didukung Tersedia di Windows XP dengan Paket Layanan 1 (SP1) dan versi Windows yang lebih baru.
Target Platform Desktop
Header ntstrsafe.h (termasuk Ntstrsafe.h)
Pustaka Ntstrsafe.lib
IRQL PASSIVE_LEVEL

Lihat juga

RtlStringCbPrintfEx

RtlStringCbVPrintf

RtlStringCchVPrintfEx