Fungsi RtlUnicodeStringCchCopyStringNEx (ntstrsafe.h)
Fungsi RtlUnicodeStringCchCopyStringNEx menyalin string ke dalam struktur UNICODE_STRING sambil membatasi ukuran string yang disalin.
Sintaks
NTSTRSAFEDDI RtlUnicodeStringCchCopyStringNEx(
[out] PUNICODE_STRING DestinationString,
[in] NTSTRSAFE_PCWSTR pszSrc,
[in] size_t cchToCopy,
[out, optional] PUNICODE_STRING RemainingString,
[in] DWORD dwFlags
);
Parameter
[out] DestinationString
Pilihan. Penunjuk ke struktur UNICODE_STRING yang menerima string yang disalin. String yang dituju *parameter pszSrc *(tidak termasuk null penghentian) disalin ke dalam buffer tempat struktur UNICODE_STRING parameter DestinationString menunjuk. Jumlah maksimum karakter dalam string adalah NTSTRSAFE_UNICODE_STRING_MAX_CCH. DestinationString bisa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.
[in] pszSrc
Pilihan. Penunjuk ke string yang akan disalin. Pointer ini bisa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.
[in] cchToCopy
Jumlah karakter yang akan disalin dari sumber ke tujuan.
[out, optional] RemainingString
Pilihan. Jika pemanggil menyediakan penunjuk non-NULL ke struktur UNICODE_STRING , fungsi mengatur anggota Buffer struktur ini ke akhir string yang digabungkan, mengatur anggota Panjang struktur ke 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. RtlUnicodeStringCchCopyStringNEx memperlakukan penunjuk buffer sumber NULL seperti string kosong (TEXT("")), yang dapat disalin. Penunjuk buffer tujuan NULL 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:
|
STRSAFE_ZERO_LENGTH_ON_FAILURE | Jika bendera ini diatur dan fungsi mengembalikan STATUS_BUFFER_OVERFLOW, panjang string tujuan diatur ke nol byte. |
Nilai kembali
RtlUnicodeStringCchCopyStringNEx mengembalikan salah satu nilai NTSTATUS berikut.
Menampilkan kode | Deskripsi |
---|---|
STATUS_SUCCESS | Status keberhasilan ini berarti data sumber ada, dan string digabungkan tanpa pemotongan. |
STATUS_BUFFER_OVERFLOW | Status peringatan ini berarti bahwa operasi penyalinan tidak selesai karena ruang yang tidak mencukupi di buffer tujuan. Jika STRSAFE_NO_TRUNCATION diatur dalam dwFlags, buffer tujuan tidak dimodifikasi. Jika bendera tidak diatur, buffer tujuan berisi versi terpotong dari string yang disalin. |
STATUS_INVALID_PARAMETER | Status kesalahan ini berarti bahwa fungsi menerima parameter input yang tidak valid. Untuk informasi selengkapnya, lihat daftar berikut ini. |
RtlUnicodeStringCchCopyStringNEx mengembalikan nilai STATUS_INVALID_PARAMETER ketika 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 cchToCopy lebih besar dari NTSTRSAFE_UNICODE_STRING_MAX_CCH.
Untuk informasi tentang cara menguji nilai NTSTATUS, lihat Menggunakan Nilai NTSTATUS.
Keterangan
Fungsi RtlUnicodeStringCchCopyStringNEx menggunakan ukuran buffer tujuan untuk memastikan bahwa operasi salin tidak menulis melewati akhir buffer. Secara default, fungsi tidak mengakhiri string yang dihasilkan dengan nilai karakter null (yaitu, dengan nol). Sebagai opsi, pemanggil dapat menggunakan bendera STRSAFE_FILL_BEHIND dan nilai byte isi nol untuk menghentikan string yang dihasilkan null yang tidak menempati seluruh buffer tujuan.
RtlUnicodeStringCchCopyStringNEx menambah fungsionalitas fungsionalitas RtlUnicodeStringCchCopyStringN dengan mengembalikan struktur UNICODE_STRING yang mengidentifikasi akhir string tujuan dan jumlah byte yang dibiarkan tidak digunakan dalam string tersebut. Anda dapat meneruskan bendera ke RtlUnicodeStringCchCopyStringNEx 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 penunjuk ini dapat berupa NULL. Jika penunjuk DestinationStringADALAH NULL, penunjuk pszSrc harus NULL atau mengarah 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 |
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