Fungsi ProbeForWrite (wdm.h)

Peringatan

Fungsi ProbeForWrite tidak disarankan untuk digunakan dalam perangkat lunak saat ini, dan hanya disertakan untuk kompatibilitas historis. Gunakan ProbeForRead sebagai gantinya saat memvalidasi buffer pengguna. Lihat Keterangan untuk informasi selengkapnya.

ProbeForWrite memeriksa bahwa buffer mode pengguna benar-benar berada di bagian mode pengguna dari ruang alamat, dapat ditulis, dan selaras dengan benar.

Sintaks

void ProbeForWrite(
  [in, out] volatile VOID *Address,
  [in]      SIZE_T        Length,
  [in]      ULONG         Alignment
);

Parameter

[in, out] Address

Menentukan awal buffer mode pengguna.

[in] Length

Menentukan panjang, dalam byte, dari buffer mode pengguna. Lihat informasi tambahan di bagian Keterangan.

[in] Alignment

Menentukan perataan yang diperlukan, dalam byte, dari awal buffer mode pengguna.

Mengembalikan nilai

Tidak ada

Keterangan

Fungsi ini biasanya tidak memberikan manfaat besar atas ProbeForRead karena driver yang kuat harus selalu siap untuk menangani perubahan perlindungan di ruang alamat virtual mode pengguna, termasuk perubahan perlindungan yang menghapus izin tulis ke buffer yang diteruskan ke driver setelah panggilan ProbeForWrite dijalankan. Karena ProbeForWrite mengakses setiap halaman di buffer yang disediakan, performa dapat berkurang karena overhead mengakses setiap halaman, terutama jika buffer yang disediakan menjelaskan wilayah ruang alamat virtual yang besar. Selain itu, karena ProbeForWrite menulis ke setiap halaman, buffer yang sama mungkin tidak digunakan dengan aman dengan beberapa permintaan driver bersamaan. Untuk alasan ini, kode driver baru harus selalu menggunakan ProbeForRead sebagai gantinya.

Tabel berikut menguraikan properti setiap rutinitas pemeriksaan buffer mode kernel:

Aktivitas	ProbeForRead	ProbeForWrite
Mengonfirmasi bahwa buffer menjelaskan wilayah dalam ruang alamat mode pengguna, jika panjangnya bukan nol	x	x
Mengonfirmasi bahwa alamat dan panjang dasar buffer tidak membungkus nilai pointer maksimum	x	x
Mengonfirmasi bahwa buffer diselaraskan ke batas perataan yang diminta, jika panjangnya bukan nol	x	x
Mengonfirmasi bahwa buffer awalnya dapat ditulis (dapat berubah kapan saja jika aplikasi mode pengguna melindungi kembali ruang alamatnya)		x
Mengakses setiap halaman di buffer (overhead tambahan)		x
Memodifikasi setiap halaman dalam buffer (dapat menyebabkan perilaku tak terduga jika buffer yang sama digunakan secara paralel dengan beberapa permintaan driver)		x

Secara historis, pada prosesor tertentu yang tidak menghormati izin baca saja untuk kode mode kernel, ada perbedaan fungsional yang bermakna antara ProbeForWrite dan ProbeForRead. Dalam kasus ini, sistem operasi sebelumnya mengandalkan ProbeForWrite melakukan pemeriksaan writability penomoran eksplisit. Perbedaan ini tidak lagi bermakna untuk prosesor apa pun yang didukung oleh Windows NT 4.0 atau yang lebih baru.

Komentar warisan

Driver mode kernel dapat menggunakan ProbeForWrite untuk memvalidasi akses tulis ke buffer yang dialokasikan di ruang pengguna. Ini paling umum digunakan selama I/O METHOD_NEITHER untuk memvalidasi buffer pengguna yang diarahkan oleh Irp-UserBuffer>.

Jika rentang memori yang ditentukan bukan rentang alamat mode pengguna yang valid atau tidak dapat ditulis (tidak ada akses, baca-saja, dan sebagainya), ProbeForWrite akan memunculkan pengecualian STATUS_ACCESS_VIOLATION. Jika awal rentang alamat tidak diselaraskan pada batas byte yang ditentukan oleh Perataan, ProbeForWrite akan menaikkan pengecualian STATUS_DATATYPE_MISALIGNMENT.

Driver harus memanggil ProbeForWrite di dalam blok coba/kecuali . Jika rutinitas menimbulkan pengecualian, driver harus menyelesaikan IRP dengan kesalahan yang sesuai. Perhatikan bahwa akses berikutnya oleh driver ke buffer mode pengguna juga harus dienkapsulasi dalam blok coba/kecuali : aplikasi berbahaya dapat memiliki utas lain yang menghapus, mengganti, atau mengubah perlindungan rentang alamat pengguna kapan saja (bahkan setelah atau selama panggilan ke ProbeForRead atau ProbeForWrite). Untuk informasi selengkapnya, lihat Menangani Pengecualian.

Jangan gunakan rutinitas ini pada alamat mode kernel; itu akan memunculkan pengecualian.

Jika bidang Irp-RequestorMode> = KernelMode, bidang Irp-AssociatedIrp.SystemBuffer> dan Irp-UserBuffer> tidak berisi alamat mode pengguna, dan panggilan ke ProbeForWrite untuk memeriksa buffer yang diarahkan oleh salah satu bidang akan menimbulkan pengecualian.

Jika Panjang = 0, ProbeForWrite tidak melakukan pemeriksaan alamat. Dalam hal ini, rutinitas tidak menimbulkan pengecualian untuk alamat yang tidak selaras atau berada di luar rentang alamat pengguna yang valid.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows 2000.
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport), IrqlExApcLte2(wdm)

Lihat juga

ProbeForRead