Fungsi RtlStringCbCatNExA (ntstrsafe.h)

  • Artikel

Fungsi RtlStringCbCatNExW dan RtlStringCbCatNExA menggabungkan dua string yang dihitung byte sambil membatasi ukuran string yang ditambahkan.

Sintaks

NTSTRSAFEDDI RtlStringCbCatNExA(
  [in, out, optional] NTSTRSAFE_PSTR pszDest,
  [in]                size_t         cbDest,
  [in, optional]      STRSAFE_PCNZCH pszSrc,
                      size_t         cbToAppend,
  [out, optional]     NTSTRSAFE_PSTR *ppszDestEnd,
  [out, optional]     size_t         *pcbRemaining,
  [in]                DWORD          dwFlags
);

Parameter

[in, out, optional] pszDest

Penunjuk ke buffer yang, pada input, berisi string yang dihentikan null di mana pszSrc akan digabungkan. Pada output, ini adalah buffer tujuan yang berisi seluruh string yang dihasilkan. String di pszSrc, hingga byte cbMaxAppend , ditambahkan ke akhir string di pszDest, dan dihentikan dengan karakter null. Pointer pszDest dapat berupa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.

[in] cbDest

Ukuran buffer tujuan, dalam byte. Buffer harus cukup besar untuk menyertakan string dan 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 pszDestADALAH NULL, cbDest 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 bisa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.

cbToAppend

Jumlah maksimum byte untuk ditambahkan ke pszDest.

[out, optional] ppszDestEnd

Jika penelepon 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] 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 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:

  • Jika STRSAFE_FILL_ON_FAILURE juga ditentukan, STRSAFE_NO_TRUNCATION mengisi buffer tujuan yang sesuai.
  • Jika tidak, buffer tujuan akan tidak dimodifikasi.

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 sepenuhnya digabungkan tanpa pemotongan, dan buffer tujuan yang dihasilkan dihentikan null.
STATUS_BUFFER_OVERFLOW Status peringatan ini berarti operasi penyalinan tidak selesai karena ruang yang tidak mencukupi 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:

  • Bendera 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 null, tetapi ukuran buffer bukan nol.
  • Penunjuk buffer tujuan adalah NULL, atau panjangnya nol, tetapi string sumber panjang bukan nol ada.

Keterangan

RtlStringCbCatNExW dan RtlStringCbCatNExA harus digunakan alih-alih fungsi berikut:

  • strncat
  • wcsncat

Ukuran, dalam byte, buffer tujuan disediakan untuk RtlStringCbCatNExW dan RtlStringCbCatNExA untuk memastikan bahwa mereka tidak menulis melewati akhir buffer.

RtlStringCbCatNEx menambahkan ke fungsionalitas RtlStringCbCatN dengan mengembalikan penunjuk ke akhir string tujuan serta jumlah byte yang tidak digunakan dalam string tersebut. Bendera dapat diteruskan ke fungsi untuk kontrol tambahan.

Gunakan RtlStringCbCatNExW untuk menangani string Unicode dan RtlStringCbCatNExA 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" RtlStringCbCatNExW
char "string" RtlStringCbCatNExA

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 berupa NULL. Jika pszDestADALAH 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