Fungsi CcMapData (ntifs.h)

Artikel
02/26/2024

Rutinitas CcMapData memetakan rentang byte tertentu dari file yang di-cache ke buffer dalam memori.

Sintaks

BOOLEAN CcMapData(
  [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 datanya akan dipetakan untuk akses baca.

[in] FileOffset

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

[in] Length

Panjang data yang diinginkan dalam byte.

[in] Flags

Bitmask bendera yang menentukan bagaimana operasi pemetaan akan dilakukan. Ini adalah kombinasi bitwise OR dari satu atau beberapa nilai berikut:

Nilai	Makna
MAP_WAIT	Penelepon dapat dimasukkan ke dalam status tunggu hingga data telah dipetakan.
MAP_NO_READ	Hanya halaman yang sudah berada dalam memori yang akan dipetakan.

Catatan Di Windows 2000dan sebelumnya, parameter ini adalah nilai BOOLEAN bernama Wait:

Tunggu

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

[out] Bcb

Pada panggilan pertama ini mengembalikan pointer ke struktur 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 dipetakan.

Mengembalikan nilai

CcMapData mengembalikan TRUE jika data untuk file yang di-cache berhasil dipetakan, FALSE jika tidak.

Keterangan

CcMapData memetakan data dalam file cache untuk akses baca. Perhatikan bahwa setelah CcMapData dipanggil, data dipetakan; tetapi tidak disematkan. Perbedaan ini penting. Data yang dipetakan tetapi tidak disematkan tidak dapat dimodifikasi dengan aman. Untuk menyematkan data, gunakan CcPinMappedData, CcPinRead, atau CcPreparePinWrite.

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

CcMapData tidak dapat memetakan 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 dipetakan tidak dapat menjangkau lebih dari satu tampilan 256 KB. Oleh karena itu, wilayah terbesar yang dapat dipetakan adalah 256 KB, dimulai pada offset selaras 256 KB dalam file.

Memetakan rentang byte dalam file yang di-cache tidak memastikan bahwa halaman tetap berada dalam memori. Selama halaman dipetakan, rentang byte dijamin untuk tetap dipetakan ke dalam ruang alamat virtual cache sistem, tetapi manajer memori dapat memunculkan halaman fisik seperti yang dibutuhkan permintaan memori sistem.

Jika bendera MAP_WAIT diatur (atau Tunggu adalah TRUE), CcMapData dijamin untuk menyelesaikan permintaan pemetaan dan mengembalikan TRUE. Jika halaman yang diperlukan dari file cache sudah berada dalam memori, data segera dipetakan dan tidak ada pemblokiran yang akan terjadi. Jika ada halaman yang diperlukan bukan penduduk, penelepon dimasukkan ke dalam status tunggu sampai semua halaman yang diperlukan telah dibuat residen dan data dapat dipetakan. Jika bendera MAP_WAIT tidak diatur (atau TungguADALAH FALSE) dan data tidak dapat segera dipetakan, CcMapData mengembalikan FALSE.

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

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

Untuk membuat cache file, gunakan CcInitializeCacheMap.