EVT_WDF_OBJECT_CONTEXT_CLEANUP fonction de rappel (wdfobject.h)
[S’applique à KMDF et UMDF]
La fonction de rappel d’événement EvtCleanupCallback d’un pilote supprime les références du pilote sur un objet afin que l’objet puisse être supprimé.
Syntaxe
EVT_WDF_OBJECT_CONTEXT_CLEANUP EvtWdfObjectContextCleanup;
void EvtWdfObjectContextCleanup(
[in] WDFOBJECT Object
)
{...}
Paramètres
[in] Object
Handle pour un objet framework.
Valeur de retour
None
Remarques
Le pilote peut spécifier une fonction de rappel EvtCleanupCallback dans une structure WDF_OBJECT_ATTRIBUTES . Cette structure est utilisée comme entrée pour toutes les méthodes d’infrastructure qui créent des objets d’infrastructure, tels que WdfDeviceCreate.
L’infrastructure appelle la fonction de rappel lorsque l’infrastructure ou un pilote tente de supprimer l’objet.
Si le pilote a appelé WdfObjectReference pour augmenter le nombre de références d’un objet, il doit fournir une fonction de rappel EvtCleanupCallback qui appelle WdfObjectDereference. Cet appel garantit que le nombre de références de l’objet est décrémenté à zéro et, par conséquent, l’infrastructure peut appeler la fonction de rappel EvtDestroyCallback du pilote, puis supprimer l’objet.
Si un pilote fournit à la fois une fonction de rappel EvtCleanupCallback et une fonction de rappel EvtDestroyCallback pour un objet, l’infrastructure appelle d’abord la fonction de rappel EvtCleanupCallback .
Une fois que l’infrastructure a appelé la fonction de rappel EvtCleanupCallback d’un objet, le pilote peut accéder à l’objet uniquement à partir de sa fonction de rappel EvtDestroyCallback . Toutefois, un pilote ne doit pas tenter d’appeler des méthodes sur un objet à partir de son EvtDestroyCallback.
Lorsqu’un pilote crée un objet, il alloue parfois des mémoires tampons spécifiques à l’objet et stocke les pointeurs de mémoire tampon dans l’espace contextuel de l’objet. La fonction de rappel EvtCleanupCallback ou EvtDestroyCallback du pilote peut libérer ces mémoires tampons.
En règle générale, si votre pilote n’appelle pas WdfObjectReference pour un objet, la fonction de rappel EvtCleanupCallback de l’objet peut libérer les allocations de contexte d’objet. Dans ce cas, le pilote n’a pas besoin d’une fonction de rappel EvtDestroyCallback pour l’objet .
Lorsqu’un objet est supprimé, l’infrastructure supprime également les enfants de l’objet. À une exception près, l’infrastructure appelle les routines EvtCleanupCallback des objets enfants avant d’appeler celles de leurs objets parents. Les pilotes sont donc assurés que l’objet parent existe toujours quand la routine EvtCleanupCallback d’un enfant s’exécute.
L’exception à ce classement garanti s’applique aux demandes d’E/S effectuées par le pilote à DISPATCH_LEVEL. Si un tel objet de requête d’E/S a un ou plusieurs enfants dont les routines EvtCleanupCallback doivent être appelées à PASSIVE_LEVEL, la requête parente peut être supprimée avant un ou plusieurs de ses enfants. Un objet nécessite un nettoyage à PASSIVE_LEVEL s’il doit attendre que quelque chose se termine ou s’il accède à la mémoire paginée.
Si le pilote tente de supprimer un tel objet (ou le parent d’un tel objet) pendant qu’il s’exécute à DISPATCH_LEVEL, le framework met en file d’attente l’EvtCleanupCallback vers un élément de travail pour un traitement ultérieur à PASSIVE_LEVEL, puis appelle le rappel de nettoyage pour l’objet parent sans déterminer si les rappels pour les enfants ont été exécutés.
Pour éviter tout problème pouvant résulter de ce comportement, les pilotes ne doivent pas définir l’objet de requête comme parent pour tout objet qui nécessite un nettoyage à PASSIVE_LEVEL. Par défaut, le parent de la plupart des objets est WDFDEVICE. Les pilotes doivent donc simplement accepter la valeur par défaut. En règle générale, si l’objet WDFDEVICE est passé en tant que paramètre (directement ou dans le cadre d’une structure) à la méthode qui crée l’objet, WDFDEVICE est le parent par défaut. Pour obtenir la liste complète des parents par défaut, consultez Résumé des objets framework.
Si l’exception ci-dessus ne s’applique pas, le framework appelle les fonctions de rappel EvtCleanupCallback de l’objet enfant avant d’appeler la fonction de rappel EvtCleanupCallback de l’objet parent. Ensuite, si le nombre de références de l’enfant est égal à zéro, le framework appelle la fonction de rappel EvtDestroyCallback de l’objet enfant. Enfin, si le nombre de références du parent est égal à zéro, le framework appelle la fonction de rappel EvtDestroyCallback de l’objet parent.
Pour plus d’informations sur la suppression d’objets framework, consultez Framework Object Life Cycle.
En règle générale, le framework appelle la fonction de rappel EvtCleanupCallback à IRQL <= DISPATCH_LEVEL. Toutefois, l’infrastructure appelle la fonction de rappel à l’adresse IRQL = PASSIVE_LEVEL dans les situations suivantes :
- Le type de handle de l’objet est WDFDEVICE, WDFDRIVER, WDFDPC, WDFINTERRUPT, WDFIOTARGET, WDFQUEUE, WDFSTRING, WDFTIMER ou WDFWORKITEM.
- Le type de handle de l’objet est WDFMEMORY ou WDFLOOKASIDE, et le pilote a spécifié PagedPool pour le paramètre PoolType sur WdfMemoryCreate ou WdfLookasideListCreate.
De même, lorsqu’un objet de minuteur est supprimé, explicitement ou parce que l’objet parent du minuteur est en cours de suppression, avant d’appeler la fonction de rappel EvtCleanupCallback du minuteur, le framework attend que toutes les instances de la fonction de rappel d’événement EvtTimerFunc du minuteur soient retournées.
À compter de la version 1.9 de l’infrastructure, le fichier d’en-tête wdfroletypes.h contient d’autres types de fonctions spécifiques au type d’objet pour la fonction de rappel EvtCleanupCallback . Ces autres types aident les outils de vérification à déterminer si le pilote utilise correctement la fonction de rappel. Utilisez le tableau suivant pour déterminer le type de fonction à utiliser.
| Type d'objet | Type de fonction |
|---|---|
| Objet d’appareil | EVT_WDF_DEVICE_CONTEXT_CLEANUP |
| Objet file d’attente d’E/S | EVT_WDF_IO_QUEUE_CONTEXT_CLEANUP_CALLBACK |
| File (objet) | EVT_WDF_FILE_CONTEXT_CLEANUP_CALLBACK |
| Tous les autres objets | EVT_WDF_OBJECT_CONTEXT_CLEANUP |
Configuration requise
| Condition requise | Valeur |
|---|---|
| Plateforme cible | Universal |
| Version KMDF minimale | 1.0 |
| Version UMDF minimale | 2.0 |
| En-tête | wdfobject.h (inclure Wdf.h) |
| IRQL | Consultez la section Notes. |