fungsi StringCbPrintf_lExA (strsafe.h)

Menulis data yang diformat ke string yang ditentukan. Ukuran buffer tujuan disediakan untuk fungsi untuk memastikan bahwa buffer tidak menulis melewati akhir buffer ini.

StringCbPrintf_lEx mirip dengan StringCbPrintfEx tetapi menyertakan parameter untuk informasi lokal.

Sintaksis

STRSAFEAPI StringCbPrintf_lExA(
  [out]           STRSAFE_LPSTR                                  pszDest,
  [in]            size_t                                         cbDest,
  [out]           STRSAFE_LPSTR                                  *ppszDestEnd,
  [out, optional] size_t                                         *pcbRemaining,
  [in]            DWORD                                          dwFlags,
  [in]            _Printf_format_string_params_(2)STRSAFE_LPCSTR pszFormat,
  [in]            _locale_t                                      locale,
                  ...                                            
);

Parameter

[out] pszDest

Buffer tujuan, yang menerima string yang diformat dan dihentikan null yang dibuat dari pszFormat dan argumennya.

[in] cbDest

Ukuran buffer tujuan, dalam byte. Nilai ini harus cukup besar untuk mengakomodasi string berformat akhir ditambah karakter null yang mengakhiri. Jumlah maksimum byte yang diizinkan adalah STRSAFE_MAX_CCH * sizeof(TCHAR).

[out] ppszDestEnd

Alamat pointer ke akhir pszDest. Jika ppszDestEnd bukan NULL dan data apa pun disalin ke dalam buffer tujuan, ini menunjuk ke karakter null yang mengakhiri di akhir string.

[out, optional] pcbRemaining

Jumlah byte yang tidak digunakan dalam pszDest, termasuk yang digunakan untuk karakter null yang mengakhiri. Jika pcbRemaining NULL, jumlah tidak disimpan atau dikembalikan.

[in] dwFlags

Satu atau beberapa nilai berikut.

Nilai Arti
STRSAFE_FILL_BEHIND_NULL
0x00000200
 Jika fungsi berhasil, byte rendah dwFlags (0) digunakan untuk mengisi bagian yang tidak diinisialisasi dari pszDest mengikuti karakter null yang mengakhiri.
STRSAFE_IGNORE_NULLS
0x00000100
 Perlakukan penunjuk string NULL seperti string kosong (TEXT("")).
STRSAFE_FILL_ON_FAILURE
0x00000400
 Jika fungsi gagal, byte rendah dwFlags (0) digunakan untuk mengisi seluruh buffer pszDest , dan buffer dihentikan null. Dalam kasus kegagalan STRSAFE_E_INSUFFICIENT_BUFFER, setiap string terpotong yang dikembalikan ditimpa.
STRSAFE_NULL_ON_FAILURE
0x00000800
 Jika fungsi gagal, pszDest diatur ke string kosong (TEXT("")). Dalam kasus kegagalan STRSAFE_E_INSUFFICIENT_BUFFER, string yang terpotong ditimpa.
STRSAFE_NO_TRUNCATION
0x00001000
 Seperti dalam kasus STRSAFE_NULL_ON_FAILURE, jika fungsi gagal, pszDest diatur ke string kosong (TEXT("")). Dalam kasus kegagalan STRSAFE_E_INSUFFICIENT_BUFFER, string yang terpotong ditimpa.

[in] pszFormat

String format. String ini harus dihentikan null. Untuk informasi selengkapnya, lihat Sintaks Spesifikasi Format .

[in] locale

Objek lokal. Untuk informasi selengkapnya, lihat _create_locale.

...

Argumen yang akan dimasukkan ke dalam string pszFormat.

Mengembalikan nilai

Fungsi ini dapat mengembalikan salah satu nilai berikut. Sangat disarankan agar Anda menggunakan BERHASIL dan makro GAGAL untuk menguji nilai pengembalian fungsi ini.

Mengembalikan kode Deskripsi
S_OK
 Ada cukup ruang untuk hasil yang akan disalin ke pszDest tanpa pemotongan, dan buffer dihentikan null.
STRSAFE_E_INVALID_PARAMETER
 Nilai dalam cbDest adalah 0 atau lebih besar dari , atau buffer tujuan sudah penuh.
STRSAFE_E_INSUFFICIENT_BUFFER
 Operasi penyalinan gagal karena ruang buffer tidak mencukupi. Tergantung pada nilai dwFlags, buffer tujuan mungkin berisi versi hasil yang dipotong dan dihentikan null. Dalam situasi di mana pemotongan dapat diterima, ini mungkin belum tentu dilihat sebagai kondisi kegagalan.

Komentar

Perilaku tidak terdefinisi jika string yang diarahkan oleh pszDest, pszFormat, atau string argumen apa pun yang tumpang tindih.

Baik pszFormat maupun pszDest tidak boleh NULL kecuali bendera STRSAFE_IGNORE_NULLS ditentukan, dalam hal ini keduanya mungkin NULL. Namun, kesalahan karena ruang yang tidak mencukup mungkin masih dikembalikan meskipun nilai NULL diabaikan.

Untuk menggunakan fungsi ini, Anda harus menentukan makro berikut dalam file header Anda, sebelum menyertakan StrSafe.h.

#define STRSAFE_LOCALE_FUNCTIONS

Nota

Header strsafe.h mendefinisikan StringCbPrintf_lEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta preprosektor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Syarat Nilai
klien minimum yang didukung Windows Vista [aplikasi desktop | Aplikasi UWP]
server minimum yang didukung Windows Server 2008 [aplikasi desktop | Aplikasi UWP]
Platform Target Windows
Header strsafe.h
  • Last updated on