Fungsi RtlStringCbPrintfW (ntstrsafe.h)

Artikel
08/07/2023

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

Sintaks

NTSTRSAFEDDI RtlStringCbPrintfW(
  [out] NTSTRSAFE_PWSTR  pszDest,
  [in]  size_t           cbDest,
  [in]  NTSTRSAFE_PCWSTR pszFormat,
        ...              
);

Parameter

[out] 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 daftar argumen fungsi.

[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).

[in] pszFormat

Penunjuk ke string teks yang dihentikan null yang berisi direktif pemformatan bergaya printf.

...

Daftar argumen yang ditafsirkan oleh fungsi berdasarkan arahan pemformatan yang terkandung dalam string pszFormat .

Menampilkan 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 dibuat tanpa pemotongan, 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. Buffer tujuan berisi versi string output yang terpotong.
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: Nilai dalam cbDest lebih besar dari ukuran buffer maksimum. Buffer tujuan sudah penuh. Penunjuk NULL ada. Panjang buffer tujuan adalah nol, tetapi string sumber panjang bukan nol ada.

Menampilkan kode

Deskripsi

STATUS_SUCCESS

Status keberhasilan ini berarti data sumber ada, string dibuat tanpa pemotongan, 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. Buffer tujuan berisi versi string output yang terpotong.

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:

Nilai dalam cbDest lebih besar dari ukuran buffer maksimum.
Buffer tujuan sudah penuh.
Penunjuk NULL ada.
Panjang buffer tujuan adalah nol, tetapi string sumber panjang bukan nol ada.

Keterangan

RtlStringCbPrintfW dan RtlStringCbPrintfA harus digunakan alih-alih fungsi berikut:

Sprintf
swprintf
_snprintf
_snwprintf

Semua fungsi ini menerima string format dan daftar argumen, menafsirkannya, dan membuat string yang diformat. Ukuran, dalam byte, buffer tujuan disediakan untuk RtlStringCbPrintfW dan RtlStringCbPrintfA untuk memastikan bahwa mereka tidak menulis melewati akhir buffer.

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

Jenis data string	String harfiah	Fungsi
WCHAR	L"string"	RtlStringCbPrintfW
char	"string"	RtlStringCbPrintfA

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 boleh NULL. Jika Anda perlu menangani nilai penunjuk string NULL , gunakan RtlStringCbPrintfEx.

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

Contoh

Contoh berikut menunjukkan penggunaan dasar RtlStringCbPrintfW menggunakan empat argumen.

int const arraysize = 30;
WCHAR pszDest[arraysize]; 
size_t cbDest = arraysize * sizeof(WCHAR);

LPCWSTR pszFormat = L"%s %d + %d = %d.";
WCHAR* pszTxt = L"The answer is";

NTSTATUS status = RtlStringCbPrintfW(pszDest, cbDest, pszFormat, pszTxt, 1, 2, 3);

String yang dihasilkan adalah "Jawabannya adalah 1 + 2 = 3." Ini terkandung dalam buffer di pszDest.

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

Lihat juga

RtlStringCbPrintfEx

RtlStringCbVPrintf

RtlStringCchPrintf