Fungsi RtlStringCchCatNExW (ntstrsafe.h)
Fungsi RtlStringCchCatNExW dan RtlStringCchCatNExA menggabungkan dua string yang dihitung karakter sambil membatasi ukuran string yang ditambahkan.
Sintaks
NTSTRSAFEDDI RtlStringCchCatNExW(
[in, out, optional] NTSTRSAFE_PWSTR pszDest,
[in] size_t cchDest,
[in, optional] STRSAFE_PCNZWCH pszSrc,
size_t cchToAppend,
[out, optional] NTSTRSAFE_PWSTR *ppszDestEnd,
[out, optional] size_t *pcchRemaining,
[in] DWORD dwFlags
);
Parameter
[in, out, optional] pszDest
Pointer ke buffer yang, pada input, berisi string null-terminated tempat pszSrc akan digabungkan. Pada output, ini adalah buffer tujuan yang berisi seluruh string yang dihasilkan. String di pszSrc, hingga karakter cchMaxAppend , ditambahkan ke akhir string di pszDest dan dihentikan dengan karakter null. Pointer pszDest bisa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.
[in] cchDest
Ukuran buffer tujuan, dalam karakter. Jumlah maksimum karakter yang diizinkan adalah NTSTRSAFE_MAX_CCH. Jika pszDest adalah NULL, cchDest harus nol.
[in, optional] pszSrc
Penunjuk ke string yang dihentikan null. String ini akan digabungkan ke akhir string yang terkandung dalam buffer di pszDest. Pointer pszSrc dapat berupa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.
cchToAppend
Jumlah maksimum karakter untuk ditambahkan ke string yang terkandung dalam buffer di pszDest.
[out, optional] ppszDestEnd
Jika pemanggil menyediakan penunjuk alamat non-NULL , maka setelah operasi perangkaian selesai, fungsi memuat alamat tersebut dengan penunjuk ke terminator string null yang dihasilkan buffer tujuan.
[out, optional] pcchRemaining
Jika pemanggil menyediakan penunjuk alamat non-NULL , fungsi memuat alamat dengan jumlah karakter yang tidak digunakan dalam buffer yang ditujukkan oleh pszDest, termasuk 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 bendera ini diatur dan fungsi berhasil, byte rendah dwFlags digunakan untuk mengisi bagian buffer tujuan yang mengikuti karakter null yang mengakhiri. |
STRSAFE_IGNORE_NULLS | Jika bendera ini diatur, baik 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 bendera ini 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 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:
|
Nilai kembali
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, lihat parameter dwFlags untuk informasi selengkapnya. |
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:
|
Keterangan
RtlStringCchCatNExW dan RtlStringCchCatNExA harus digunakan alih-alih fungsi berikut:
- strncat
- wcsncat
Ukuran, dalam karakter, dari buffer tujuan disediakan untuk RtlStringCchCatNExW dan RtlStringCchCatNExA untuk memastikan bahwa fungsi tidak menulis melewati akhir buffer.
RtlStringCchCatNExW dan RtlStringCchCatNExA menambahkan ke fungsionalitas RtlStringCchCatN dengan mengembalikan pointer ke akhir string tujuan, serta jumlah karakter yang dibiarkan tidak digunakan dalam string tersebut. Bendera dapat diteruskan ke fungsi untuk kontrol tambahan.
Gunakan RtlStringCchCatNExW untuk menangani string Unicode dan RtlStringCchCatNExA 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" | RtlStringCchCatNExW |
char | "string" | RtlStringCchCatnExA |
Jika pszSrc dan pszDest menunjuk ke string yang tumpang tindih, perilaku fungsi tidak terdefinisi.
Baik pszSrc maupun pszDest tidak dapat berupa NULL kecuali bendera STRSAFE_IGNORE_NULLS diatur, dalam hal ini baik atau keduanya dapat NULL. Jika pszDest adalah NULL, pszSrc harus NULL atau menunjuk ke string kosong.
Untuk informasi selengkapnya tentang fungsi string aman, lihat Menggunakan fungsi string aman.
Persyaratan
Persyaratan | Nilai |
---|---|
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 | Bagaimanapun, jika string yang dimanipulasi selalu berada dalam memori, jika tidak, PASSIVE_LEVEL |
Lihat juga
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk