Fungsi RtlStringCchCopyUnicodeStringEx (ntstrsafe.h)
Fungsi RtlStringCchCopyUnicodeStringEx menyalin konten struktur UNICODE_STRING ke tujuan tertentu.
Sintaks
NTSTRSAFEDDI RtlStringCchCopyUnicodeStringEx(
[out] NTSTRSAFE_PWSTR pszDest,
[in] size_t cchDest,
[in] PCUNICODE_STRING SourceString,
[out] NTSTRSAFE_PWSTR *ppszDestEnd,
[out, optional] size_t *pcchRemaining,
[in] DWORD dwFlags
);
Parameter
[out] pszDest
Pilihan. Penunjuk ke buffer yang menerima string yang disalin. String yang ditunjukkan struktur UNICODE_STRING parameter SourceString disalin ke buffer di pszDest dan dihentikan dengan karakter null. Pointer ini bisa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.
[in] cchDest
Ukuran, dalam karakter, dari buffer tujuan. Buffer harus cukup besar untuk string dan karakter null yang mengakhiri. Jumlah maksimum karakter dalam buffer adalah NTSTRSAFE_MAX_CCH.
[in] SourceString
Pilihan. Penunjuk ke struktur UNICODE_STRING yang berisi string yang akan disalin. Jumlah maksimum karakter dalam string adalah NTSTRSAFE_UNICODE_STRING_MAX_CCH. Pointer ini bisa NULL, tetapi hanya jika STRSAFE_IGNORE_NULLS diatur dalam dwFlags.
[out] ppszDestEnd
Pilihan. Jika pemanggil menyediakan penunjuk alamat non-NULL , maka setelah operasi salin selesai, fungsi memuat alamat tersebut dengan penunjuk ke terminator string null yang dihasilkan buffer tujuan.
[out, optional] pcchRemaining
Pilihan. Jika pemanggil menyediakan penunjuk alamat non-NULL , fungsi memuat alamat dengan jumlah karakter yang tidak digunakan yang ada di buffer yang dituju 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 penunjuk sumber atau tujuan, atau keduanya, bisa NULL. RtlStringCchCopyUnicodeStringEx 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, 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
RtlStringCchCopyUnicodeStringEx mengembalikan salah satu nilai NTSTATUS berikut.
Menampilkan kode | Deskripsi |
---|---|
STATUS_SUCCESS | Status keberhasilan ini berarti bahwa data sumber ada, string disalin tanpa pemotongan, dan buffer tujuan yang dihasilkan dihentikan null. |
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. |
RtlStringCchCopyUnicodeStringEx 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.
- Nilai dalam cchDest lebih besar dari ukuran buffer maksimum.
- Buffer tujuan (yang menunjuk pszDest ) sudah penuh.
- Penunjuk buffer adalah NULL dan bendera STRSAFE_IGNORE_NULLS tidak ditentukan.
- 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.
Untuk informasi tentang cara menguji nilai NTSTATUS, lihat Menggunakan Nilai NTSTATUS.
Keterangan
Fungsi RtlStringCchCopyUnicodeStringEx menggunakan ukuran buffer tujuan (yang ditentukan parameter cchDest ) untuk memastikan bahwa operasi salin tidak menulis melewati akhir buffer.
RtlStringCchCopyUnicodeStringEx menambahkan fungsionalitas fungsi RtlStringCchCopyUnicodeString dengan mengembalikan penunjuk ke akhir string tujuan dan jumlah byte yang dibiarkan tidak digunakan dalam string tersebut. Anda dapat meneruskan bendera ke fungsi untuk kontrol tambahan.
Jika string sumber dan tujuan tumpang tindih, perilaku fungsi tidak terdefinisi.
*SourceString *dan penunjuk pszDest tidak boleh NULL kecuali bendera STRSAFE_IGNORE_NULLS diatur dalam dwFlags. Jika STRSAFE_IGNORE_NULLS diatur, salah satu atau kedua titik ini dapat berupa NULL. Jika penunjuk pszDestadalah NULL, penunjuk SourceString harus NULL atau struktur UNICODE_STRING harus menjelaskan 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