Fungsi FsRtlCopyRead (ntifs.h)

  • Artikel

FsRtlCopyRead rutin menyalin data dari file yang di-cache ke buffer pengguna.

Sintaks

BOOLEAN FsRtlCopyRead(
  [in]  PFILE_OBJECT     FileObject,
  [in]  PLARGE_INTEGER   FileOffset,
  [in]  ULONG            Length,
  [in]  BOOLEAN          Wait,
  [in]  ULONG            LockKey,
  [out] PVOID            Buffer,
  [out] PIO_STATUS_BLOCK IoStatus,
  [in]  PDEVICE_OBJECT   DeviceObject
);

Parameter

[in] FileObject

Penunjuk ke objek file untuk file cache tempat data akan dibaca.

[in] FileOffset

Memulai byte offset dalam file yang di-cache.

[in] Length

Panjang byte data yang akan dibaca.

[in] Wait

Atur ke TRUE jika penelepon dapat dimasukkan ke dalam status tunggu hingga semua data telah disalin, FALSE jika tidak.

[in] LockKey

Nilai yang terkait dengan rentang byte untuk dikunci. Jika rentang untuk mengunci tumpang tindih dengan rentang lain yang sudah dikunci dengan kunci tidak termasuk, atau jika rentang yang akan dibaca adalah subrange dari rentang lain yang sudah dikunci secara tidak termasuk, nilai dalam parameter ini harus menjadi kunci untuk kunci yang tidak termasuk Kunci harus ditahan oleh proses induk utas panggilan. Jika tidak, parameter ini tidak berpengaruh.

[out] Buffer

Penunjuk ke buffer tempat data akan disalin.

[out] IoStatus

Penunjuk ke struktur yang dialokasikan penelepon yang menerima status penyelesaian akhir dan informasi tentang operasi. Jika data berhasil disalin, IoStatus.Status berisi STATUS_SUCCESS. Jika tidak semua data berhasil disalin, IoStatus.Information berisi jumlah byte aktual yang disalin.

[in] DeviceObject

Objek perangkat untuk perangkat yang menyimpan data file.

Nilai kembali

FsRtlCopyRead mengembalikan TRUE jika permintaan salin selesai, FALSE jika tidak. Perhatikan bahwa nilai pengembalian TRUE tidak selalu berarti bahwa operasi penyalinan berhasil.

Jika FsRtlCopyRead mengembalikan FALSE, atau jika konten IoStatus menunjukkan bahwa operasi salin gagal, pemanggil harus mengalokasikan IRP baca alih-alih memanggil FsRtlCopyRead.

Keterangan

Daripada menerapkan rutinitas baca I/O cepat khusus sistem file, pengembang sistem file yang mendukung penembolokan file harus mempertimbangkan untuk menggunakan FsRtlCopyRead sebagai titik masuk sistem file untuk memproses permintaan baca I/O yang cepat. Ini mengharuskan driverEntry sistem file rutin mengatur titik masuk FastIoRead ke FsRtlCopyRead dalam struktur FAST_IO_DISPATCH objek driver sistem file. Selain itu, sistem file harus melakukan hal berikut:

  1. Untuk setiap file di mana I/O cepat mungkin dilakukan, sistem file harus mengalokasikan dan menginisialisasi struktur FSRTL_COMMON_FCB_HEADER.

    Di sebagian besar sistem file, ini dicapai dengan menyertakan struktur FSRTL_COMMON_FCB_HEADER dalam blok kontrol file (FCB) atau struktur sebanding yang digunakan untuk mempertahankan status file terbuka.

    Penyimpanan untuk struktur FSRTL_COMMON_FCB_HEADER biasanya dialokasikan dari kumpulan halaman.

  2. Untuk setiap file di mana I/O cepat mungkin dilakukan, sistem file harus menautkan objek file apa pun untuk file ke struktur FSRTL_COMMON_FCB_HEADER. Ini dilakukan dengan mengatur setiap anggota FsContext objek file untuk menunjuk ke struktur ini (atau FCB atau struktur lain yang berisi struktur FSRTL_COMMON_FCB_HEADER).

  3. Saat membuat cache file, sistem file harus mengatur anggota IsFastIoPossible dari struktur FSRTL_COMMON_FCB_HEADER file ke nilai yang sesuai. Nilai ini harus diperbarui sesuai kebutuhan selama file tetap di-cache.

    Secara khusus, sistem file harus mengatur anggota IsFastIoPossible dari struktur FSRTL_COMMON_FCB_HEADER ke FastIoIsQuestionable segera setelah ada kunci rentang byte eksklusif pada file cache.

Jika Wait is TRUE, FsRtlCopyRead dijamin untuk menyelesaikan permintaan salin dan mengembalikan TRUE. Jika halaman yang diperlukan dari file yang di-cache sudah berada dalam memori, data akan segera disalin dan tidak ada pemblokiran yang akan terjadi. Jika ada halaman yang diperlukan tidak residen, penelepon akan dimasukkan ke dalam status tunggu sampai semua halaman yang diperlukan telah dibuat residen dan data dapat disalin.

Jika Wait is FALSE, FsRtlCopyRead akan menolak untuk memblokir, dan akan mengembalikan FALSE, jika tidak dapat memperoleh sumber daya utama file atau jika halaman yang diperlukan dari file yang di-cache belum berada di memori.

Rutinitas FastIoCheckIfPossible sistem file bertanggung jawab untuk memastikan bahwa rentang byte yang ditentukan oleh FileOffset dan Panjang tidak menyertakan rentang byte yang dikunci secara eksklusif yang pemanggilnya tidak melewati nilai LockKey yang sesuai. Jika sistem file menggunakan rutinitas dukungan FsRtlXxxLockYyy untuk mengelola kunci rentang byte, ini dapat dicapai dengan memanggil FsRtlFastCheckLockForRead dari rutinitas FastIoCheckIfPossible sebelum memanggil FsRtlCopyRead.

Untuk menyimpan file, gunakan rutinitas CcInitializeCacheMap .

Persyaratan

Persyaratan Nilai
Target Platform Universal
Header ntifs.h (termasuk Ntifs.h)
Pustaka NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
Aturan kepatuhan DDI PowerIrpDDis(wdm)

Lihat juga

CcInitializeCacheMap

FsRtlCopyWrite

FsRtlFastCheckLockForRead