Utilisation d’éléments de travail

Avertissement

UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2.

Les exemples UMDF 1 archivés se trouvent dans la Windows 11, version 22H2 - Mise à jour des exemples de pilotes de mai 2022.

Pour plus d’informations, consultez Prise en main avec UMDF.

Un élément de travail est une tâche qu’un pilote effectue dans une fonction de rappel d’événement OnWorkItem . Ces fonctions s’exécutent de manière asynchrone.

Les pilotes UMDF utilisent généralement des éléments de travail si un OnInterruptIsr doit effectuer un traitement supplémentaire sans retarder l’exécution de la demande de service d’interruption (ISR), car la ligne d’interruption peut être partagée par plusieurs appareils.

En règle générale, la fonction de rappel OnInterruptIsr d’un pilote crée un objet d’élément de travail et l’ajoute à la file d’attente d’éléments de travail du système. Par la suite, un thread thread de pool de threads met l’objet en file d’attente et appelle la fonction de rappel OnWorkItem de l’élément de travail.

Configuration d’un élément de travail

Pour configurer un élément de travail, votre pilote doit :

1. Créez l’élément de travail.

   Votre pilote appelle IWDFDevice3::CreateWorkItem pour créer un objet d’élément de travail et pour identifier une fonction de rappel OnWorkItem qui traitera l’élément de travail.

2. Stockez des informations sur l’élément de travail.

   En règle générale, les pilotes utilisent la mémoire contextuelle de l’objet élément de travail pour stocker des informations sur la tâche que la fonction de rappel OnWorkItem doit effectuer. Lorsque la fonction de rappel OnWorkItem est appelée, elle peut récupérer les informations en accédant à cette mémoire contextuelle. Pour plus d’informations sur l’allocation et l’accès à la mémoire contextuelle, consultezIWDFObject::AssignContext.

3. Ajoutez l’élément de travail à la file d’attente d’éléments de travail du système.

   Votre pilote appelle IWDFWorkItem::Enqueue, ce qui ajoute l’élément de travail du pilote à la file d’attente d’éléments de travail.

Lorsque votre pilote appelle IWDFDevice3::CreateWorkItem, il peut éventuellement fournir un objet parent (par exemple un objet d’appareil ou un objet de file d’attente). Lorsque le système supprime cet objet, il supprime également tous les éléments de travail existants associés à l’objet.

Utilisation de la fonction de rappel WorkItem

Une fois l’élément de travail ajouté à la file d’attente d’éléments de travail, il reste dans la file d’attente jusqu’à ce qu’un thread worker système soit disponible. Le thread de travail système supprime l’élément de travail de la file d’attente, puis appelle la fonction de rappel OnWorkItem du pilote, en passant l’objet élément de travail comme entrée.

En règle générale, la fonction de rappel OnWorkItem effectue les étapes suivantes :

1. Obtient des informations fournies par le pilote sur l’élément de travail en accédant à la mémoire contextuelle de l’objet élément de travail.
2. Exécute la tâche que vous avez spécifiée. Si nécessaire, la fonction de rappel peut appeler IWDFWorkItem::GetParentObject pour déterminer l’objet parent de l’élément de travail.
3. Si le pilote met en file d’attente l’élément de travail, indique que le handle de l’élément de travail est désormais disponible pour réutilisation.

Certains pilotes peuvent avoir besoin d’appeler IWDFWorkItem::Flush pour vider leurs éléments de travail de la file d’attente d’éléments de travail. Si un pilote appelle la méthode Flush , la méthode ne retourne pas tant qu’un thread de travail n’a pas supprimé l’élément de travail spécifié de la file d’attente d’éléments de travail et appelé la fonction de rappel OnWorkItem du pilote et que la fonction de rappel OnWorkItem n’a pas été retournée après le traitement de l’élément de travail.