WdfWorkItemCreate, fonction (wdfworkitem.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfWorkItemCreate crée un objet d’élément de travail framework, qui peut ensuite être ajouté à la file d’attente d’éléments de travail du système.

Syntaxe

NTSTATUS WdfWorkItemCreate(
  [in]  PWDF_WORKITEM_CONFIG   Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFWORKITEM            *WorkItem
);

Paramètres

[in] Config

Pointeur vers une structure de WDF_WORKITEM_CONFIG allouée par l’appelant que le pilote doit déjà avoir initialisée en appelant WDF_WORKITEM_CONFIG_INIT.

[in] Attributes

Pointeur vers une structure de WDF_OBJECT_ATTRIBUTES allouée par l’appelant qui spécifie des attributs pour l’objet d’élément de travail.

[out] WorkItem

Pointeur vers une variable qui reçoit un handle vers le nouvel objet d’élément de travail.

Valeur retournée

WdfWorkItemCreate retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été fourni.
STATUS_INVALID_DEVICE_REQUEST	Le parent de l’objet d’élément de travail n’est pas un objet d’appareil ou l’ancêtre d’un objet d’appareil.
STATUS_INSUFFICIENT_RESOURCES	Les ressources système étaient insuffisantes pour créer un objet d’élément de travail.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	Le membre AutomaticSerialization de la structure WDF_WORKITEM_CONFIG vers laquelle le paramètre Config pointe est TRUE, mais le niveau d’exécution de l’objet parent n’est pas WdfExecutionLevelPassive.
STATUS_WDF_PARENT_NOT_SPECIFIED	Le paramètre Attributes était NULL, ou le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES spécifiée par Attributes était NULL.

Remarques

Après qu’un pilote a appelé WdfWorkItemCreate pour créer un élément de travail, il stocke généralement des informations spécifiques à l’élément dans la mémoire contextuelle de l’objet élément de travail. La fonction de rappel EvtWorkItem du pilote, qui effectue les tâches de l’élément de travail, peut accéder à ces informations pour déterminer les tâches qu’il doit effectuer. (Pour plus d’informations sur le stockage d’informations dans la mémoire contextuelle, consultez Framework Object Context Space.)

Après avoir stocké les informations sur l’élément de travail, le pilote doit appeler WdfWorkItemEnqueue pour ajouter l’élément de travail à la file d’attente d’éléments de travail du système. Lorsqu’un thread de travail système devient disponible, le thread supprime l’élément de travail de la file d’attente et appelle la fonction de rappel EvtWorkItem .

Lorsque le pilote crée un objet élément de travail, il doit spécifier un objet parent pour l’objet élément de travail dans le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES . L’objet parent doit être un objet d’appareil d’infrastructure ou tout objet dont la chaîne de parents conduit à un objet d’appareil d’infrastructure. L’infrastructure supprime l’objet élément de travail lorsqu’il supprime l’objet d’appareil.

Pour supprimer l’objet d’élément de travail précédemment, le pilote peut appeler WdfObjectDelete, comme décrit dans Utilisation d’éléments de travail d’infrastructure.

Le pilote peut récupérer l’objet parent d’un élément de travail en appelant WdfWorkItemGetParentObject.

Si votre pilote fournit des fonctions de rappel EvtCleanupCallback ou EvtDestroyCallback pour l’objet d’élément de travail, notez que l’infrastructure appelle ces fonctions de rappel à l’adresse IRQL = PASSIVE_LEVEL.

Pour plus d’informations sur les éléments de travail, consultez Utilisation des éléments de travail d’infrastructure.

Exemples

L’exemple de code suivant initialise une structure WDF_OBJECT_ATTRIBUTES , initialise une structure WDF_WORKITEM_CONFIG et appelle WdfWorkItemCreate.

NTSTATUS  status = STATUS_SUCCESS;
PWORKER_ITEM_CONTEXT  context;
WDF_OBJECT_ATTRIBUTES  attributes;
WDF_WORKITEM_CONFIG  workitemConfig;
WDFWORKITEM  hWorkItem;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
                                       &attributes,
                                       WORKER_ITEM_CONTEXT
                                       );
attributes.ParentObject = FdoData->WdfDevice;

WDF_WORKITEM_CONFIG_INIT(
                         &workitemConfig,
                         CallbackFunction
                         );

status = WdfWorkItemCreate(
                            &workitemConfig,
                            &attributes,
                            &hWorkItem
                            );
if (!NT_SUCCESS(status)) {
    return status;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfworkitem.h (include Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Voir aussi

WdfWorkItemEnqueue

Partager via