Fungsi CcPinMappedData (ntifs.h)

Artikel
08/07/2023

Rutinitas CcPinMappedData menyematkan rentang byte yang ditentukan dari file yang di-cache.

Sintaks

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

Parameter

[in] FileObject

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

[in] FileOffset

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

[in] Length

Panjang byte data yang akan disematkan.

[in] Flags

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

Bendera	Makna
PIN_WAIT	Penelepon 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.

[in, out] Bcb

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

Mengembalikan nilai

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

Keterangan

Pengembalian yang berhasil dari CcPinMappedData menjamin bahwa data yang sebelumnya dipetakan dalam panggilan ke CcMapData disematkan dalam cache dan data dalam rentang yang ditentukan dapat dimodifikasi dengan aman. Jika penelepon kemudian memodifikasi data yang disematkan oleh CcPinMappedData, pemanggil juga harus memanggil CcSetDirtyPinnedData sehingga data yang dimodifikasi pada akhirnya akan ditulis ke disk.

CcPinMappedData 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 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.

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

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

Tidak perlu memanggil CcUnpinData setelah memanggil CcPinMappedData karena referensi pin cocok dengan CcMapData.