EVT_WDF_OBJECT_CONTEXT_CLEANUP funzione di callback (wdfobject.h)
[Si applica a KMDF e UMDF]
La funzione di callback dell'evento EvtCleanupCallback di un driver rimuove i riferimenti del driver su un oggetto in modo che l'oggetto possa essere eliminato.
Sintassi
EVT_WDF_OBJECT_CONTEXT_CLEANUP EvtWdfObjectContextCleanup;
void EvtWdfObjectContextCleanup(
[in] WDFOBJECT Object
)
{...}
Parametri
[in] Object
Handle per un oggetto framework.
Valore restituito
nessuno
Osservazioni
Il driver può specificare una funzione di callback EvtCleanupCallback in una struttura WDF_OBJECT_ATTRIBUTES . Questa struttura viene usata come input per tutti i metodi del framework che creano oggetti framework, ad esempio WdfDeviceCreate.
Il framework chiama la funzione di callback quando il framework o un driver tenta di eliminare l'oggetto.
Se il driver ha chiamato WdfObjectReference per aumentare il numero di riferimenti di un oggetto, il driver deve fornire una funzione di callback EvtCleanupCallback che chiama WdfObjectDereference. Questa chiamata garantisce che il conteggio dei riferimenti dell'oggetto venga decrementato su zero e, di conseguenza, il framework può chiamare la funzione di callback EvtDestroyCallback del driver e quindi eliminare l'oggetto.
Se un driver fornisce sia una funzione di callback EvtCleanupCallback che una funzione di callback EvtDestroyCallback per un oggetto, il framework chiama prima la funzione di callback EvtCleanupCallback .
Dopo che il framework chiama la funzione di callback EvtCleanupCallback di un oggetto, il driver può accedere all'oggetto solo dalla relativa funzione di callback EvtDestroyCallback . Tuttavia, un driver non deve tentare di chiamare metodi su un oggetto dal relativo EvtDestroyCallback.
Quando un driver crea un oggetto, talvolta alloca buffer di memoria specifici dell'oggetto e archivia i puntatori del buffer nello spazio di contesto dell'oggetto. La funzione di callback EvtCleanupCallback o EvtDestroyCallback del driver può deallocare questi buffer di memoria.
In genere, se il driver non chiama WdfObjectReference per un oggetto, la funzione di callback EvtCleanupCallback dell'oggetto può deallocare le allocazioni del contesto dell'oggetto. In questo caso, il driver non necessita di una funzione di callback EvtDestroyCallback per l'oggetto.
Quando un oggetto viene eliminato, il framework elimina anche gli elementi figlio dell'oggetto. Con un'eccezione, il framework chiama le routine EvtCleanupCallback degli oggetti figlio prima di chiamare quelli dei relativi oggetti padre, pertanto i driver garantiscono che l'oggetto padre esista ancora quando viene eseguita la routine EvtCleanupCallback di un figlio.
L'eccezione a questo ordinamento garantito si applica alle richieste di I/O completate dal driver in DISPATCH_LEVEL. Se un oggetto richiesta di I/O di questo tipo ha uno o più elementi figlio le cui routine EvtCleanupCallback devono essere chiamate a PASSIVE_LEVEL, la richiesta padre potrebbe essere eliminata prima di uno o più elementi figlio. Un oggetto richiede la pulizia in PASSIVE_LEVEL se deve attendere il completamento di un elemento o se accede alla memoria di paging.
Se il driver tenta di eliminare tale oggetto (o l'elemento padre di tale oggetto) mentre è in esecuzione in DISPATCH_LEVEL, il framework accoda EvtCleanupCallback a un elemento di lavoro per un'elaborazione successiva in PASSIVE_LEVEL e quindi chiama il callback di pulizia per l'oggetto padre senza determinare se i callback per gli elementi figlio sono stati eseguiti.
Per evitare eventuali problemi che potrebbero derivare da questo comportamento, i driver non devono impostare l'oggetto richiesta come padre per qualsiasi oggetto che richiede la pulizia in PASSIVE_LEVEL. Per impostazione predefinita, l'elemento padre per la maggior parte degli oggetti è WDFDEVICE, quindi i driver devono accettare solo l'impostazione predefinita. In genere, se l'oggetto WDFDEVICE viene passato come parametro (direttamente o come parte di una struttura) al metodo che crea l'oggetto , WDFDEVICE è l'elemento padre predefinito. Per un elenco completo degli elementi padre predefiniti, vedere Riepilogo degli oggetti framework.
Se l'eccezione precedente non si applica, il framework chiama le funzioni di callback EvtCleanupCallback dell'oggetto figlio prima di chiamare la funzione di callback EvtCleanupCallback dell'oggetto padre. Successivamente, se il conteggio dei riferimenti del figlio è zero, il framework chiama la funzione di callback EvtDestroyCallback dell'oggetto figlio. Infine, se il conteggio dei riferimenti dell'elemento padre è zero, il framework chiama la funzione di callback EvtDestroyCallback dell'oggetto padre.
Per altre informazioni sull'eliminazione di oggetti framework, vedere Ciclo di vita degli oggetti framework.
In genere, il framework chiama la funzione di callback EvtCleanupCallback in IRQL <= DISPATCH_LEVEL. Tuttavia, il framework chiama la funzione di callback in IRQL = PASSIVE_LEVEL nelle situazioni seguenti:
- Il tipo di handle dell'oggetto è WDFDEVICE, WDFDRIVER, WDFDPC, WDFINTERRUPT, WDFIOTARGET, WDFQUEUE, WDFSTRING, WDFTIMER o WDFWORKITEM.
- Il tipo di handle dell'oggetto è WDFMEMORY o WDFLOOKASIDE e il driver ha specificato PagedPool per il parametro PoolType in WdfMemoryCreate o WdfLookasideListCreate.
Analogamente, quando un oggetto timer viene eliminato, in modo esplicito o perché l'oggetto padre del timer viene eliminato, quindi prima di chiamare la funzione di callback EvtCleanupCallback del timer, il framework attende fino a quando non vengono restituite tutte le istanze della funzione di callback dell'evento EvtTimerFunc del timer.
A partire dalla versione 1.9 del framework, il file di intestazione wdfroletypes.h contiene alcuni tipi di funzione alternativi specifici del tipo di oggetto per la funzione di callback EvtCleanupCallback . Questi tipi alternativi consentono agli strumenti di verifica di determinare se il driver usa correttamente la funzione di callback. Usare la tabella seguente per determinare il tipo di funzione da usare.
| Tipo di oggetto | Tipo di funzione |
|---|---|
| Oggetto dispositivo | EVT_WDF_DEVICE_CONTEXT_CLEANUP |
| Oggetto coda di I/O | EVT_WDF_IO_QUEUE_CONTEXT_CLEANUP_CALLBACK |
| File (oggetto) | EVT_WDF_FILE_CONTEXT_CLEANUP_CALLBACK |
| Tutti gli altri oggetti | EVT_WDF_OBJECT_CONTEXT_CLEANUP |
Requisiti
| Requisito | Valore |
|---|---|
| Piattaforma di destinazione | Universale |
| Versione KMDF minima | 1.0 |
| Versione UMDF minima | 2,0 |
| Intestazione | wdfobject.h (include Wdf.h) |
| IRQL | Vedere la sezione Osservazioni. |