Fungsi CcPinRead (ntifs.h)

Artikel
08/07/2023

Rutinitas CcPinRead menyematkan rentang byte yang ditentukan dari file yang di-cache dan membaca data yang disematkan ke dalam buffer dalam memori.

Sintaks

BOOLEAN CcPinRead(
  [in]  PFILE_OBJECT   FileObject,
  [in]  PLARGE_INTEGER FileOffset,
  [in]  ULONG          Length,
  [in]  ULONG          Flags,
  [out] PVOID          *Bcb,
  [out] PVOID          *Buffer
);

Parameter

[in] FileObject

Penunjuk ke objek file untuk file yang di-cache tempat rentang data akan disematkan.

[in] FileOffset

Penunjuk ke variabel yang menentukan offset byte awal dalam file yang di-cache tempat data yang diinginkan berada.

[in] Length

Panjang data yang diinginkan dalam byte.

[in] Flags

Bitmask bendera yang menentukan bagaimana operasi penyematan akan dilakukan. Kombinasi ORed dari satu atau beberapa nilai berikut:

Nilai	Makna
PIN_WAIT	Pemanggil dapat dimasukkan ke dalam status tunggu hingga data telah disematkan.
PIN_EXCLUSIVE	Blok kontrol buffer (BCB) akan diperoleh secara eksklusif. Jika bendera ini diatur, PIN_WAIT juga harus diatur.
PIN_NO_READ	Hanya halaman yang sudah berada dalam memori yang akan disematkan. Jika bendera ini diatur, PIN_WAIT juga harus diatur.
PIN_IF_BCB	Data akan disematkan hanya jika BCB sudah ada. Jika tidak, pin gagal dan Bcb diatur ke NULL.

[out] Bcb

Pada panggilan pertama ini mengembalikan penunjuk ke blok kontrol buffer (BCB). Pointer ini harus disediakan sebagai input pada semua panggilan berikutnya untuk buffer ini.

[out] Buffer

Penunjuk ke buffer yang berisi data yang disematkan.

Mengembalikan nilai

CcPinRead mengembalikan TRUE jika data untuk file yang di-cache disematkan dan berhasil dibaca, FALSE jika tidak.

Keterangan

Jika bendera PIN_WAIT diatur, CcPinRead dijamin akan menyelesaikan permintaan penyematan dan mengembalikan TRUE. Jika halaman yang diperlukan dari file yang di-cache sudah berada dalam memori, data segera disematkan dan tidak ada pemblokiran yang terjadi. Jika ada halaman yang diperlukan bukan penduduk, penelepon dimasukkan ke dalam status tunggu sampai semua halaman yang diperlukan telah dibuat sebagai residen dan data dapat disematkan. Jika bendera PIN_WAIT tidak diatur, tetapi data tidak dapat segera disematkan, CcPinRead mengembalikan FALSE, dan nilai parameter outputnya tidak ada artinya.

Jika penelepon kemudian memodifikasi data yang dibaca oleh CcPinRead, pemanggil juga harus memanggil CcSetDirtyPinnedData sehingga data yang dimodifikasi pada akhirnya akan ditulis ke disk.

Setiap panggilan yang berhasil ke CcPinRead harus dicocokkan dengan panggilan berikutnya ke CcUnpinData.

Penunjuk yang dikembalikan dalam Buffer valid hingga CcUnpinData dipanggil. Jika CcPinMappedData dipanggil saat pointer ini masih valid, pointer tetap valid setelah panggilan ke CcPinMappedData (tetapi hanya sampai CcUnpinData dipanggil).

CcPinRead tidak dapat menyematkan data di seluruh batas tampilan di manajer cache. Manajer cache mengelola file dalam sistem dalam tampilan selaras 256 KB. (Ukuran tampilan manajer cache ditentukan oleh VACB_MAPPING_GRANULARITY konstanta yang ditentukan sistem, yang diatur ke 256 KB dalam ntifs.h.) Wilayah yang disematkan tidak dapat menjangkau lebih dari satu tampilan 256 KB. Oleh karena itu, wilayah terbesar yang dapat disematkan adalah 256 KB, dimulai dari offset selaras 256 KB dalam file.

Menyematkan rentang byte dalam file yang di-cache tidak memastikan bahwa halaman tetap berada dalam memori. Selama halaman disematkan, rentang byte dijamin untuk tetap dipetakan ke ruang alamat virtual cache sistem, tetapi manajer memori dapat mem-page out halaman fisik sesuai kebutuhan memori sistem.

Jika terjadi kegagalan, CcPinRead menimbulkan pengecualian status untuk kegagalan tertentu tersebut. Misalnya, jika kegagalan alokasi kumpulan terjadi, CcPinRead menimbulkan pengecualian STATUS_INSUFFICIENT_RESOURCES; jika terjadi kesalahan I/O, CcPinRead menaikkan pengecualian status kesalahan I/O. Oleh karena itu, untuk mendapatkan kontrol jika kegagalan terjadi, driver harus membungkus panggilan ke CcPinRead dalam pernyataan try-except atau try-finally .

Untuk memetakan data untuk file yang di-cache, gunakan rutinitas CcMapData . Untuk menyimpan file, gunakan CcInitializeCacheMap.