EVT_WDF_OBJECT_CONTEXT_CLEANUP fungsi panggilan balik (wdfobject.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Fungsi panggilan balik peristiwa EvtCleanupCallback driver menghapus referensi driver pada objek sehingga objek dapat dihapus.

Sintaks

EVT_WDF_OBJECT_CONTEXT_CLEANUP EvtWdfObjectContextCleanup;

void EvtWdfObjectContextCleanup(
  [in] WDFOBJECT Object
)
{...}

Parameter

[in] Object

Handel ke objek kerangka kerja.

Nilai kembali

Tidak ada

Keterangan

Driver dapat menentukan fungsi panggilan balik EvtCleanupCallback dalam struktur WDF_OBJECT_ATTRIBUTES . Struktur ini digunakan sebagai input ke semua metode kerangka kerja yang membuat objek kerangka kerja, seperti WdfDeviceCreate.

Kerangka kerja memanggil fungsi panggilan balik saat kerangka kerja atau driver mencoba menghapus objek.

Jika driver telah memanggil WdfObjectReference untuk meningkatkan jumlah referensi objek, driver harus menyediakan fungsi panggilan balik EvtCleanupCallback yang memanggil WdfObjectDereference. Panggilan ini memastikan bahwa jumlah referensi objek dikurangi menjadi nol dan, sebagai hasilnya, kerangka kerja dapat memanggil fungsi panggilan balik EvtDestroyCallback driver lalu menghapus objek.

Jika driver menyediakan fungsi panggilan balik EvtCleanupCallback dan fungsi panggilan balik EvtDestroyCallback untuk objek, kerangka kerja memanggil fungsi panggilan balik EvtCleanupCallback terlebih dahulu.

Setelah kerangka kerja memanggil fungsi panggilan balik EvtCleanupCallback objek, driver hanya dapat mengakses objek dari fungsi panggilan balik EvtDestroyCallback-nya . Namun, driver tidak boleh mencoba memanggil metode pada objek dari EvtDestroyCallback-nya.

Ketika driver membuat objek, terkadang mengalokasikan buffer memori khusus objek dan menyimpan penunjuk buffer di ruang konteks objek. Fungsi panggilan balik EvtCleanupCallback atau EvtDestroyCallback driver dapat membatalkan alokasi buffer memori ini.

Biasanya, jika driver Anda tidak memanggil WdfObjectReference untuk objek, fungsi panggilan balik EvtCleanupCallback objek dapat membatalkan alokasi konteks objek. Dalam hal ini, driver tidak memerlukan fungsi panggilan balik EvtDestroyCallback untuk objek .

Saat objek dihapus, kerangka kerja juga menghapus turunan objek. Dengan satu pengecualian, kerangka kerja memanggil rutinitas EvtCleanupCallback dari objek anak sebelum memanggil objek induk mereka, sehingga driver dijamin bahwa objek induk masih ada ketika rutinitas EvtCleanupCallback anak berjalan.

Pengecualian untuk pemesanan yang dijamin ini berlaku untuk permintaan I/O yang diselesaikan driver pada DISPATCH_LEVEL. Jika objek permintaan I/O seperti itu memiliki satu atau beberapa anak yang rutinitas EvtCleanupCallback harus dipanggil pada PASSIVE_LEVEL, permintaan induk mungkin dihapus sebelum satu atau beberapa anaknya. Objek memerlukan pembersihan pada PASSIVE_LEVEL jika harus menunggu sesuatu selesai atau jika mengakses memori halaman.

Jika driver mencoba menghapus objek tersebut (atau induk objek tersebut) saat berjalan pada DISPATCH_LEVEL, kerangka kerja mengantrekan EvtCleanupCallback ke item kerja untuk diproses nanti di PASSIVE_LEVEL dan kemudian memanggil panggilan balik pembersihan untuk objek induk tanpa menentukan apakah panggilan balik untuk anak-anak telah berjalan.

Untuk menghindari masalah yang mungkin diakibatkan oleh perilaku ini, driver tidak boleh mengatur objek permintaan sebagai induk untuk objek apa pun yang memerlukan pembersihan saat PASSIVE_LEVEL. Secara default, induk untuk sebagian besar objek adalah WDFDEVICE, sehingga driver hanya boleh menerima default. Umumnya, jika objek WDFDEVICE diteruskan sebagai parameter (baik secara langsung atau sebagai bagian dari struktur) ke metode yang membuat objek, WDFDEVICE adalah induk default. Untuk daftar lengkap induk default, lihat Ringkasan Objek Kerangka Kerja.

Jika pengecualian di atas tidak berlaku, kerangka kerja memanggil fungsi panggilan balik EvtCleanupCallback objek anak sebelum memanggil fungsi panggilan balik EvtCleanupCallback objek induk. Selanjutnya, jika jumlah referensi anak adalah nol, kerangka kerja memanggil fungsi panggilan balik EvtDestroyCallback objek anak. Terakhir, jika jumlah referensi induk adalah nol, kerangka kerja memanggil fungsi panggilan balik EvtDestroyCallback objek induk.

Untuk informasi selengkapnya tentang menghapus objek kerangka kerja, lihat Siklus Hidup Objek Kerangka Kerja.

Biasanya, kerangka kerja memanggil fungsi panggilan balik EvtCleanupCallback di IRQL <= DISPATCH_LEVEL. Namun, kerangka kerja memanggil fungsi panggilan balik di IRQL = PASSIVE_LEVEL dalam situasi berikut:

Jenis handel objek adalah WDFDEVICE, WDFDRIVER, WDFDPC, WDFINTERRUPT, WDFIOTARGET, WDFQUEUE, WDFSTRING, WDFTIMER, atau WDFWORKITEM.
Jenis handel objek adalah WDFMEMORY atau WDFLOOKASIDE, dan driver telah menentukan PagedPool untuk parameter PoolType ke WdfMemoryCreate atau WdfLookasideListCreate.

Saat objek item kerja dihapus, baik secara eksplisit atau karena objek induk item kerja sedang dihapus, maka sebelum memanggil fungsi panggilan balik EvtCleanupCallback item kerja, kerangka kerja menunggu hingga semua instans fungsi panggilan balik EvtWorkItem item kerja telah kembali. Untuk informasi selengkapnya, lihat WdfWorkItemEnqueue.

Demikian pula, ketika objek timer dihapus, baik secara eksplisit atau karena objek induk timer sedang dihapus, maka sebelum memanggil fungsi panggilan balik EvtCleanupCallback timer, kerangka kerja menunggu sampai semua instans fungsi panggilan balik peristiwa EvtTimerFunc timer telah kembali.

Dimulai dengan versi 1.9 dari kerangka kerja, file header wdfroletypes.h berisi beberapa jenis fungsi alternatif, khusus jenis objek untuk fungsi panggilan balik EvtCleanupCallback . Jenis alternatif ini membantu alat verifikasi untuk menentukan apakah driver menggunakan fungsi panggilan balik dengan benar. Gunakan tabel berikut untuk menentukan jenis fungsi mana yang akan digunakan.

Jenis Objek	Jenis Fungsi
Objek perangkat	EVT_WDF_DEVICE_CONTEXT_CLEANUP
Objek antrean I/O	EVT_WDF_IO_QUEUE_CONTEXT_CLEANUP_CALLBACK
Objek file	EVT_WDF_FILE_CONTEXT_CLEANUP_CALLBACK
Semua objek lainnya	EVT_WDF_OBJECT_CONTEXT_CLEANUP