Objek File Kerangka Kerja

Ketika aplikasi atau driver mencoba mengakses perangkat, biasanya dengan membuat atau membuka file, sistem operasi mengirim permintaan pembuatan file ke tumpukan driver. Ketika aplikasi atau driver telah selesai menggunakan perangkat, sistem mengirim pembersihan file dan menutup permintaan ke tumpukan driver. Jenis permintaan dari ketiga permintaan ini adalah WdfRequestTypeCreate, WdfRequestTypeCleanup, dan WdfRequestTypeClose.

Biasanya, kecuali driver Anda telah memanggil WdfDeviceInitSetExclusive, driver harus melakukan operasi khusus file atau khusus akses lainnya ketika menerima permintaan pembuatan, pembersihan, dan penutupan file, karena beberapa file dapat dibuka secara bersamaan atau beberapa aplikasi dapat mengakses perangkat secara bersamaan. Oleh karena itu, driver harus melacak permintaan I/O yang terkait dengan setiap file atau aplikasi.

Kerangka kerja mendefinisikan objek file kerangka kerja, yang mewakili aplikasi atau sarana driver untuk mengakses perangkat, seperti file, direktori, volume, slot email, pipa bernama, atau seluruh perangkat. Nama file dapat dikaitkan dengan objek file, tetapi arti dari nama file khusus driver. Untuk informasi selengkapnya tentang nama file, lihat Mengontrol Akses Namespace Perangkat.

Jika driver Anda harus menangani operasi file, driver harus memanggil WdfDeviceInitSetFileObjectConfig dari dalam fungsi panggilan balik EvtDriverDeviceAdd . Metode WdfDeviceInitSetFileObjectConfig menerima struktur WDF_FILEOBJECT_CONFIG sebagai input. Driver menggunakan struktur ini untuk mendaftarkan fungsi panggilan balik EvtDeviceFileCreate, EvtFileCleanup, dan EvtFileClose dan, secara opsional, untuk menunjukkan apakah kerangka kerja harus membuat objek file kerangka kerja setiap kali driver menerima permintaan pembuatan file.

Sebagian besar driver yang menangani operasi file menyimpan informasi khusus file di ruang konteks objek file kerangka kerja. Jika driver Anda menangani operasi file tetapi tidak perlu menyimpan informasi di ruang konteks objek file, kerangka kerja tidak harus membuat objek file kerangka kerja untuk driver.

Membuat atau Membuka File

Ketika kerangka kerja menerima permintaan pembuatan file untuk driver fungsi Anda, itu:

1. Membuat objek file kerangka kerja yang mewakili file, kecuali driver sebelumnya menunjukkan bahwa ia tidak perlu menggunakan objek file kerangka kerja.

2. Memanggil fungsi panggilan balik EvtDeviceFileCreate driver Anda, jika driver telah mendaftarkan fungsi panggilan balik.

Fungsi panggilan balik EvtDeviceFileCreate biasanya mendapatkan informasi tentang file, seperti nama dan bendera objek file. Driver biasanya menyimpan informasi ini di ruang konteks objek file kerangka kerja.

Alih-alih menyediakan fungsi panggilan balik EvtDeviceFileCreate , driver dapat memanggil WdfDeviceConfigureRequestDispatching untuk mengatur antrean I/O untuk menerima semua permintaan pembuatan file (jenis permintaan WdfRequestTypeCreate ). Driver kemudian akan menerima permintaan pembuatan file dalam penangan permintaan EvtIoDefault antrean. (Antrean I/O tidak dapat menerima permintaan pembuatan file jika anggota Antrean Default dari struktur WDF_IO_QUEUE_CONFIG antrean diatur ke TRUE.)

Jika driver Anda tidak menyediakan fungsi panggilan balik EvtDeviceFileCreate dan tidak menyiapkan antrean I/O untuk menangani permintaan I/O WdfRequestTypeCreate-typed, kerangka kerja:

• Menyelesaikan semua permintaan pembuatan file untuk driver dengan nilai status STATUS_SUCCESS, jika driver Anda adalah driver fungsi.

• Meneruskan semua permintaan pembuatan file ke driver berikutnya yang lebih rendah, jika driver Anda adalah driver filter.

(Untuk melihat bagaimana Anda dapat mengubah perilaku ini, lihat anggota AutoForwardCleanupClose dari struktur WDF_FILEOBJECT_CONFIG .)

Catatan Jika driver fungsi Anda tidak menyediakan antarmuka perangkat apa pun yang dapat digunakan aplikasi untuk mengakses perangkat driver, driver harus menyediakan fungsi panggilan balik EvtDeviceFileCreate yang menyelesaikan semua permintaan pembuatan file dengan nilai status yang NT_SUCCESS(status) sama dengan FALSE. Jika tidak, aplikasi berbahaya mungkin mencoba mengakses perangkat dengan menggunakan nama objek perangkat fisik (PDO) perangkat. (Semua PDO memiliki nama.)

Jika driver meneruskan permintaan pembuatan ke target I/O, driver tidak boleh menyelesaikan permintaan dengan nilai status kegagalan kecuali driver menerima nilai status kegagalan dari target I/O. Jika tidak, driver yang lebih rendah tidak akan diberi tahu bahwa permintaan pembuatan gagal dan mungkin mencoba beroperasi seolah-olah file terbuka.

Jika driver meneruskan permintaan pembuatan ke target I/O, driver tidak dapat mengatur bendera WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET jika kerangka kerja telah membuat objek file kerangka kerja untuk permintaan pembuatan. Oleh karena itu, driver tidak dapat mengatur bendera WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET untuk permintaan pembuatan kecuali juga mengatur bendera WdfFileObjectNotRequired karena driver tidak akan dapat membersihkan WDFFILEOBJECT jika driver yang lebih rendah dalam tumpukan gagal permintaan pembuatan. Sebagai gantinya, driver dapat menggunakan opsi kirim lainnya, misalnya, mengirim secara asinkron dengan rutinitas penyelesaian atau mengirim secara sinkron. Dalam kedua kasus, driver harus memanggil WdfRequestComplete ketika mendapatkan kembali kontrol.

Perhatikan bahwa jika driver menyelesaikan permintaan pembuatan dengan status kesalahan, kerangka kerja menghapus objek file kerangka kerja tetapi tidak memanggil fungsi panggilan balik EvtFileCleanup atau EvtFileClose driver. Oleh karena itu, jika driver mengalokasikan memori khusus objek tambahan di luar ruang konteks objek file, driver harus menyediakan fungsi panggilan balik EvtCleanupCallback atau EvtDestroyCallback yang menghapus memori yang dialokasikan.

Untuk Windows Vista dan yang lebih baru, permintaan pembuatan berkas bisa dibatalkan. Versi sistem operasi Windows yang lebih lama tidak mendukung pembatalan permintaan pembuatan file.

Sistem selalu membuat objek file Windows Driver Model (WDM) untuk setiap permintaan pembuatan yang berasal dari aplikasi pengguna. Jika driver mengirim permintaan pembuatan, driver mungkin tidak membuat objek file WDM untuk permintaan tersebut. Biasanya, kerangka kerja tidak membuat objek file kerangka kerja jika objek file WDM tidak ada. Namun, jika driver Anda telah memanggil WdfDeviceInitSetExclusive dan jika driver telah mengatur WdfFileObjectWdfCannotUseFsContexts di anggota FileObjectClass dari struktur WDF_FILEOBJECT_CONFIG , kerangka kerja akan membuat objek file kerangka kerja bahkan jika objek file WDM tidak ada.

Mendapatkan Informasi File

Fungsi panggilan balik EvtDeviceFileCreate driver dapat memanggil satu atau beberapa metode objek berikut untuk mendapatkan informasi tentang akses aplikasi atau driver ke perangkat:

WdfFileObjectGetFileName
Mengembalikan nama file yang terkandung dalam objek file kerangka kerja.

WdfFileObjectGetFlags
Mengembalikan bendera yang terkandung dalam objek file kerangka kerja.

WdfFileObjectWdmGetFileObject
Mengembalikan objek file WDM yang terkait dengan objek file kerangka kerja.

WdfRequestGetParameters
Mengambil parameter yang terkait dengan objek permintaan kerangka kerja. Jika jenis permintaan adalah WdfRequestTypeCreate, anggota Parameters.Create dari struktur WDF_REQUEST_PARAMETERS berisi informasi tentang permintaan pembuatan file.

Biasanya, driver menyimpan informasi file di ruang konteks objek file kerangka kerja. Ketika driver Anda mendapatkan permintaan I/O dari satu jika antrean I/O-nya, driver dapat memanggil WdfRequestGetFileObject untuk mendapatkan handel ke objek file kerangka kerja yang terkait dengan permintaan. Driver kemudian dapat mengambil informasi file yang disimpan dalam ruang konteks objek file kerangka kerja.

Driver Anda dapat mencari antrean I/O untuk permintaan yang terkait dengan file tertentu dengan memanggil WdfIoQueueRetrieveRequestByFileObject.

Jika driver Anda memiliki penunjuk ke struktur DEVICE_OBJECT WDM, driver dapat memanggil WdfDeviceGetFileObject untuk mendapatkan handel ke objek file kerangka kerja yang terkait dengan objek perangkat WDM.

Menutup File

Ketika aplikasi atau driver lain menutup file, kerangka kerja menerima permintaan pembersihan dan permintaan tutup untuk driver Anda. Kerangka kerja:

1. Memanggil fungsi panggilan balik EvtFileCleanup dan EvtFileClose driver Anda, jika driver telah mendaftarkan fungsi panggilan balik ini.

2. Menghapus objek file kerangka kerja yang mewakili file.

Fungsi panggilan balik EvtFileCleanup dan EvtFileClose driver menerima handel ke objek file kerangka kerja. Driver dapat memanggil WdfFileObjectGetDevice untuk menentukan objek perangkat kerangka kerja mana yang terkait dengan objek file kerangka kerja.