Fungsi RtlUnicodeStringCchCatStringNEx (ntstrsafe.h)

Artikel
08/07/2023

Fungsi RtlUnicodeStringCchCatStringNEx menggabungkan dua string saat string tujuan terkandung dalam struktur UNICODE_STRING , sambil membatasi ukuran string yang ditambahkan.

Sintaks

NTSTRSAFEDDI RtlUnicodeStringCchCatStringNEx(
  [in, out]       PUNICODE_STRING  DestinationString,
  [in]            NTSTRSAFE_PCWSTR pszSrc,
  [in]            size_t           cchToAppend,
  [out, optional] PUNICODE_STRING  RemainingString,
  [in]            DWORD            dwFlags
);

Parameter

[in, out] DestinationString

Pilihan. Penunjuk ke struktur UNICODE_STRING . Struktur ini mencakup buffer yang, pada input, berisi string tempat string sumber akan digabungkan. Pada output, buffer ini adalah buffer tujuan yang berisi seluruh string yang dihasilkan. String sumber (tidak termasuk penghentian null) ditambahkan ke akhir string tujuan. Jumlah maksimum karakter dalam buffer string struktur adalah NTSTRSAFE_UNICODE_STRING_MAX_CCH. DestinationString bisa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.

[in] pszSrc

Penunjuk yang disediakan penelepon ke string yang dihentikan null. String ini akan digabungkan ke akhir string yang dijelaskan DestinationString . pszSrc bisa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.

[in] cchToAppend

Jumlah maksimum karakter untuk ditambahkan ke string yang dijelaskan parameter DestinationString .

[out, optional] RemainingString

Pilihan. Jika pemanggil memasok penunjuk non-NULL ke struktur UNICODE_STRING , fungsi mengatur anggota Buffer struktur ini ke akhir string yang digabungkan, mengatur anggota Panjang struktur menjadi nol, dan mengatur anggota MaximumLength struktur ke jumlah byte yang tersisa di buffer tujuan. RemainingString bisa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.

[in] dwFlags

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

Nilai	Makna
STRSAFE_FILL_BEHIND	Jika bendera ini diatur dan fungsi berhasil, byte rendah dwFlags digunakan untuk mengisi bagian buffer tujuan yang mengikuti karakter terakhir dalam string.
STRSAFE_IGNORE_NULLS	Jika bendera ini diatur, penunjuk sumber atau tujuan, atau keduanya, bisa NULL. RtlUnicodeStringCchCatStringNEx memperlakukan penunjuk buffer sumber NULL seperti string kosong (TEXT("")), yang dapat disalin. NULL penunjuk buffer tujuan 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. 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.
STRSAFE_ZERO_LENGTH_ON_FAILURE	Jika bendera ini diatur dan fungsi mengembalikan STATUS_BUFFER_OVERFLOW, panjang string tujuan diatur ke nol byte.

Nilai kembali

RtlUnicodeStringCchCatStringNEx mengembalikan salah satu nilai NTSTATUS berikut.

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Status keberhasilan ini berarti data sumber ada, dan string digabungkan tanpa pemotokan.
STATUS_BUFFER_OVERFLOW	Status peringatan ini berarti bahwa operasi penggabungan tidak selesai karena ruang yang tidak mencukuum di buffer tujuan. Jika STRSAFE_NO_TRUNCATION diatur, lihat parameter dwFlags untuk informasi selengkapnya.
STATUS_INVALID_PARAMETER	Status kesalahan ini berarti bahwa fungsi menerima parameter input yang tidak valid. Untuk informasi selengkapnya, lihat daftar berikut ini.

RtlUnicodeStringCchCatStringNEx mengembalikan nilai STATUS_INVALID_PARAMETER saat salah satu hal berikut ini terjadi:

Isi struktur UNICODE_STRING tidak valid.
Bendera yang tidak valid ditentukan dalam dwFlags.
Buffer tujuan sudah penuh.
Penunjuk buffer adalah NULL dan bendera STRSAFE_IGNORE_NULLS tidak ditentukan dalam dwFlags.
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.
Nilai parameter cchToAppend lebih besar dari NTSTRSAFE_UNICODE_STRING_MAX_CCH.

Untuk informasi tentang cara menguji nilai NTSTATUS, lihat Menggunakan Nilai NTSTATUS.

Keterangan

Fungsi RtlUnicodeStringCchCatStringNEx menggunakan ukuran buffer tujuan untuk memastikan bahwa operasi penggabungan tidak menulis melewati akhir buffer. Secara default, fungsi tidak mengakhiri string yang dihasilkan dengan nilai karakter null (yaitu, dengan nol). Sebagai opsi, penelepon dapat menggunakan bendera STRSAFE_FILL_BEHIND dan nilai byte isian nol untuk menghentikan string yang dihasilkan null yang tidak menempati seluruh buffer tujuan.

RtlUnicodeStringCchCatStringNExmenambahkan fungsionalitas fungsionalitas RtlUnicodeStringCchCatStringN dengan mengembalikan struktur UNICODE_STRING yang mengidentifikasi akhir string tujuan dan jumlah byte yang dibiarkan tidak digunakan dalam string tersebut. Bendera dapat diteruskan ke RtlUnicodeStringCchCatStringNEx untuk kontrol tambahan.

Jika string sumber dan tujuan tumpang tindih, perilaku fungsi tidak terdefinisi.

Pointer pszSrc dan DestinationString tidak boleh NULL kecuali bendera STRSAFE_IGNORE_NULLS diatur dalam dwFlags. Jika STRSAFE_IGNORE_NULLS diatur, salah satu atau kedua pointer ini dapat berupa NULL. Jika penunjuk DestinationString adalah NULL, penunjuk 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 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