Fungsi CcPreparePinWrite (ntifs.h)

Artikel
08/07/2023

CcPreparePinWrite rutin menyematkan rentang byte yang ditentukan dari file cache untuk akses tulis.

Sintaks

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

Parameter

[in] FileObject

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

[in] FileOffset

Penunjuk ke variabel yang menentukan offset byte awal dalam file tempat data akan ditulis.

[in] Length

Panjang data yang diinginkan dalam byte.

[in] Zero

Atur ke TRUE jika buffer akan di-nol saat dikembalikan. Parameter ini diabaikan jika bendera PIN_CALLER_TRACKS_DIRTY_DATA diatur dalam parameter Bendera .

[in] Flags

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

Nilai	Makna
PIN_WAIT	Penelepon dapat dimasukkan ke dalam status tunggu hingga data telah disematkan.
PIN_EXCLUSIVE	Blok kontrol buffer (BCB) akan diperoleh secara eksklusif.
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 tidak ada BCB yang dikembalikan.
PIN_CALLER_TRACKS_DIRTY_DATA	Penelepon bertanggung jawab untuk melacak halaman kotor. Jika bendera ini diatur, semua bendera lainnya akan diabaikan. Bendera ini tersedia di Microsoft Windows Server 2003 SP1 dan yang lebih baru.

[out] Bcb

Penunjuk buram ke blok kontrol buffer yang disematkan (BCB). Pointer ini harus disediakan sebagai input pada setiap panggilan berikutnya ke CcPreparePinWrite atau CcUnpinData untuk buffer ini.

[out] Buffer

Mengembalikan penunjuk ke data yang diinginkan, valid hingga buffer tidak disematkan atau dibebaskan.

Nilai kembali

CcPreparePinWrite mengembalikan TRUE jika file cache berhasil disematkan, FALSE jika tidak.

Keterangan

CcPreparePinWrite menyematkan halaman file yang ditentukan dalam cache sistem. Halaman yang akan ditimpa sepenuhnya mungkin dipenuhi dengan halaman nol.

Jika bendera PIN_WAIT diatur, CcPreparePinWrite dijamin untuk menyelesaikan permintaan persiapan dan mengembalikan TRUE. Jika semua halaman dapat segera disiapkan, tidak ada pemblokiran yang terjadi. Jika ada halaman yang diperlukan tidak residen, penelepon dimasukkan ke dalam status tunggu sampai semua halaman yang diperlukan telah dibuat residen dan halaman dapat disiapkan. Jika bendera PIN_WAIT tidak diatur, tetapi tidak semua halaman dapat segera disiapkan, CcPreparePinWrite mengembalikan FALSE, dan nilai parameter outputnya tidak berarti.

Microsoft Windows Server 2003 SP1 dan yang lebih baru: Bendera PIN_CALLER_TRACKS_DIRTY_DATA umumnya digunakan dalam kasus di mana sistem file mengelola file log yang ditulis tetapi tidak dibaca. Karena data file yang ada akan ditimpa dan tidak dibaca, manajer cache dapat mengembalikan halaman nol alih-alih kesalahan di halaman aktual data file dari disk. Jika bendera ini diatur, manajer cache tidak melacak halaman kotor. Penelepon bertanggung jawab untuk melacak halaman kotor apa pun. Perhatikan bahwa CcPreparePinWrite hanya boleh digunakan untuk menyematkan data dengan cara ini jika buffer pada akhirnya akan dibersihkan ke disk. Sebelum memanggil CcFlushCache untuk menyiram buffer ke disk, pemanggil harus terlebih dahulu memanggil MmSetAddressRangeModified untuk memberi tahu manajer memori bahwa halaman yang ditentukan dalam buffer cache sistem kotor dan harus ditulis.

Setiap panggilan yang berhasil ke CcPreparePinWrite harus dicocokkan dengan panggilan berikutnya ke CcUnpinData. Jika CcPreparePinWrite dipanggil beberapa kali untuk data yang sama, CcUnpinData harus dipanggil dalam jumlah yang sama.

Pointer 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).

CcPreparePinWrite 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 di 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 pada 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 dalam ruang alamat virtual cache sistem, tetapi manajer memori dapat memunculkan halaman fisik sesuai kebutuhan memori sistem.

Tidak perlu memanggil CcSetDirtyPinnedData setelah memanggil CcPreparePinWrite. Jika CcPreparePinWrite mengembalikan TRUE, BCB sudah ditandai sebagai kotor.

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