EVT_WDF_OBJECT_CONTEXT_CLEANUP Rückruffunktion (wdfobject.h)
[Gilt für KMDF und UMDF]
Die EvtCleanupCallback-Ereignisrückruffunktion eines Treibers entfernt die Verweise des Treibers auf ein Objekt, sodass das Objekt gelöscht werden kann.
Syntax
EVT_WDF_OBJECT_CONTEXT_CLEANUP EvtWdfObjectContextCleanup;
void EvtWdfObjectContextCleanup(
[in] WDFOBJECT Object
)
{...}
Parameter
[in] Object
Ein Handle für ein Frameworkobjekt.
Rückgabewert
Keine
Bemerkungen
Der Treiber kann eine EvtCleanupCallback-Rückruffunktion in einer WDF_OBJECT_ATTRIBUTES-Struktur angeben. Diese Struktur wird als Eingabe für alle Frameworkmethoden verwendet, die Frameworkobjekte erstellen, z. B. WdfDeviceCreate.
Das Framework ruft die Rückruffunktion auf, wenn entweder das Framework oder ein Treiber versucht, das Objekt zu löschen.
Wenn der Treiber WdfObjectReference aufgerufen hat, um die Verweisanzahl eines Objekts zu erhöhen, muss der Treiber eine EvtCleanupCallback-Rückruffunktion bereitstellen, die WdfObjectDereference aufruft. Durch diesen Aufruf wird sichergestellt, dass die Verweisanzahl des Objekts auf 0 (null) dekrementiert wird, sodass das Framework die Rückruffunktion EvtDestroyCallback des Treibers aufrufen und dann das Objekt löschen kann.
Wenn ein Treiber sowohl eine EvtCleanupCallback-Rückruffunktion als auch eine EvtDestroyCallback-Rückruffunktion für ein Objekt bereitstellt, ruft das Framework zuerst die Rückruffunktion EvtCleanupCallback auf.
Nachdem das Framework die EvtCleanupCallback-Rückruffunktion eines Objekts aufgerufen hat, kann der Treiber nur über seine EvtDestroyCallback-Rückruffunktion auf das Objekt zugreifen. Ein Treiber sollte jedoch nicht versuchen, Methoden für ein Objekt aus seinem EvtDestroyCallback aufzurufen.
Wenn ein Treiber ein Objekt erstellt, ordnet er manchmal objektspezifische Speicherpuffer zu und speichert die Pufferzeiger im Kontextbereich des Objekts. Die Rückruffunktion EvtCleanupCallback oder EvtDestroyCallback des Treibers kann die Zuordnung dieser Speicherpuffer aufheben.
Wenn Ihr Treiber WdfObjectReference nicht für ein Objekt aufruft, kann die EvtCleanupCallback-Rückruffunktion des Objekts die Zuordnung von Objektkontextzuordnungen aufheben. In diesem Fall benötigt der Treiber keine EvtDestroyCallback-Rückruffunktion für das -Objekt.
Wenn ein Objekt gelöscht wird, löscht das Framework auch die untergeordneten Elemente des Objekts. Mit einer Ausnahme ruft das Framework die EvtCleanupCallback-Routinen untergeordneter Objekte auf, bevor die der übergeordneten Objekte aufgerufen werden, sodass Treiber garantiert sind, dass das übergeordnete Objekt weiterhin vorhanden ist, wenn die EvtCleanupCallback-Routine eines untergeordneten Objekts ausgeführt wird.
Die Ausnahme von dieser garantierten Reihenfolge gilt für E/A-Anforderungen, die der Treiber bei DISPATCH_LEVEL. Wenn ein solches E/A-Anforderungsobjekt über ein oder mehrere untergeordnete Elemente verfügt, deren EvtCleanupCallback-Routinen bei PASSIVE_LEVEL aufgerufen werden müssen, kann die übergeordnete Anforderung vor mindestens einem ihrer untergeordneten Elemente gelöscht werden. Ein Objekt erfordert eine Bereinigung bei PASSIVE_LEVEL, wenn es warten muss, bis etwas abgeschlossen ist oder auf ausgelagerten Arbeitsspeicher zugreift.
Wenn der Treiber versucht, ein solches Objekt (oder das übergeordnete Objekt eines solchen Objekts) zu löschen, während es bei DISPATCH_LEVEL ausgeführt wird, stellt das Framework evtCleanupCallback zur späteren Verarbeitung unter PASSIVE_LEVEL in die Warteschlange und ruft dann den Bereinigungsrückruf für das übergeordnete Objekt auf, ohne zu bestimmen, ob die Rückrufe für die untergeordneten Elemente ausgeführt wurden.
Um Probleme zu vermeiden, die sich aus diesem Verhalten ergeben können, sollten Treiber das Anforderungsobjekt nicht als übergeordnetes Objekt festlegen, für das bei PASSIVE_LEVEL eine Bereinigung erforderlich ist. Standardmäßig ist das übergeordnete Element für die meisten Objekte WDFDEVICE, sodass Treiber nur die Standardeinstellung akzeptieren sollten. Wenn das WDFDEVICE-Objekt als Parameter (entweder direkt oder als Teil einer -Struktur) an die Methode übergeben wird, die das Objekt erstellt, ist das WDFDEVICE das standardmäßige übergeordnete Element. Eine vollständige Liste der standardmäßigen übergeordneten Elemente finden Sie unter Zusammenfassung der Frameworkobjekte.
Wenn die obige Ausnahme nicht zutrifft, ruft das Framework die EvtCleanupCallback-Rückruffunktionen des untergeordneten Objekts auf, bevor die EvtCleanupCallback-Rückruffunktion des übergeordneten Objekts aufgerufen wird. Wenn die Verweisanzahl des untergeordneten Objekts null ist, ruft das Framework als Nächstes die EvtDestroyCallback-Rückruffunktion des untergeordneten Objekts auf. Wenn die Verweisanzahl des übergeordneten Objekts null ist, ruft das Framework schließlich die EvtDestroyCallback-Rückruffunktion des übergeordneten Objekts auf.
Weitere Informationen zum Löschen von Frameworkobjekten finden Sie unter Framework Object Life Cycle.
In der Regel ruft das Framework die Rückruffunktion EvtCleanupCallback unter IRQL <= DISPATCH_LEVEL auf. Das Framework ruft jedoch die Rückruffunktion unter IRQL = PASSIVE_LEVEL in den folgenden Situationen auf:
- Der Handletyp des Objekts ist WDFDEVICE, WDFDRIVER, WDFDPC, WDFINTERRUPT, WDFIOTARGET, WDFQUEUE, WDFSTRING, WDFTIMER oder WDFWORKITEM.
- Der Handletyp des Objekts ist WDFMEMORY oder WDFLOOKASIDE, und der Treiber hat PagedPool für den PoolType-Parameter auf WdfMemoryCreate oder WdfLookasideListCreate angegeben.
Wenn ein Timerobjekt gelöscht wird, entweder explizit oder weil das übergeordnete Objekt des Timers gelöscht wird, wartet das Framework vor dem Aufruf der EvtCleanupCallback-Rückruffunktion des Timers, bis alle Instanzen der EvtTimerFunc-Ereignisrückruffunktion des Timers zurückgegeben wurden.
Ab Version 1.9 des Frameworks enthält die Headerdatei wdfroletypes.h einige alternative, objekttypspezifische Funktionstypen für die Rückruffunktion EvtCleanupCallback . Mit diesen alternativen Typen können Überprüfungstools ermittelt werden, ob der Treiber die Rückruffunktion ordnungsgemäß verwendet. Verwenden Sie die folgende Tabelle, um zu bestimmen, welcher Funktionstyp verwendet werden soll.
| Objekttyp | Funktionstyp |
|---|---|
| Geräteobjekt | EVT_WDF_DEVICE_CONTEXT_CLEANUP |
| E/A-Warteschlangenobjekt | EVT_WDF_IO_QUEUE_CONTEXT_CLEANUP_CALLBACK |
| File-Objekt | EVT_WDF_FILE_CONTEXT_CLEANUP_CALLBACK |
| Alle anderen Objekte | EVT_WDF_OBJECT_CONTEXT_CLEANUP |
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Universell |
| KMDF-Mindestversion | 1.0 |
| UMDF-Mindestversion | 2.0 |
| Kopfzeile | wdfobject.h (einschließen von Wdf.h) |
| IRQL | Weitere Informationen finden Sie im Abschnitt mit den Hinweisen. |