WdfWorkItemCreate-Funktion (wdfworkitem.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfWorkItemCreate-Methode erstellt ein Framework-Arbeitselementobjekt, das anschließend der Arbeitsaufgabenwarteschlange des Systems hinzugefügt werden kann.

Syntax

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

Parameter

[in] Config

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_WORKITEM_CONFIG Struktur, die der Treiber bereits initialisiert haben muss, indem WDF_WORKITEM_CONFIG_INITaufgerufen wird.

[in] Attributes

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_OBJECT_ATTRIBUTES Struktur, die Attribute für das Arbeitselementobjekt angibt.

[out] WorkItem

Ein Zeiger auf eine Variable, die ein Handle für das neue Arbeitselementobjekt empfängt.

Rückgabewert

WdfWorkItemCreate gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Es wurde ein ungültiger Parameter angegeben.
STATUS_INVALID_DEVICE_REQUEST	Das übergeordnete Objekt des Arbeitselements ist kein Geräteobjekt oder das Vorgängerobjekt eines Geräteobjekts.
STATUS_INSUFFICIENT_RESOURCES	Es gab nicht genügend Systemressourcen, um ein Arbeitselementobjekt zu erstellen.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	Die AutomaticSerialization Member in der WDF_WORKITEM_CONFIG Struktur, auf die der Config Parameter verweist, ist TRUE, die Ausführungsebene des übergeordneten Objekts ist jedoch nicht WdfExecutionLevelPassive.
STATUS_WDF_PARENT_NOT_SPECIFIED	Der parameter Attributes war NULL, oder das ParentObject Member der WDF_OBJECT_ATTRIBUTES Struktur, die Attributes angibt, war NULL-.

Bemerkungen

Nachdem ein Treiber WdfWorkItemCreate aufgerufen hat, um eine Arbeitsaufgabe zu erstellen, speichert er in der Regel elementspezifische Informationen im Kontextspeicher des Arbeitselementobjekts. Die EvtWorkItem Rückruffunktion des Treibers, die die Aufgaben der Arbeitsaufgabe ausführt, kann auf diese Informationen zugreifen, um die aufgaben zu bestimmen, die sie ausführen muss. (Weitere Informationen zum Speichern von Informationen im Kontextspeicher finden Sie unter Framework Object Context Space.)

Nach dem Speichern von Arbeitselementinformationen muss der Treiber WdfWorkItemEnqueue- aufrufen, um die Arbeitsaufgabe zur Arbeitsaufgabenwarteschlange des Systems hinzuzufügen. Wenn ein Systemarbeitsthread verfügbar ist, entfernt der Thread die Arbeitsaufgabe aus der Warteschlange und ruft die EvtWorkItem Rückruffunktion auf.

Wenn der Treiber ein Arbeitselementobjekt erstellt, muss es ein übergeordnetes Objekt für das Arbeitselementobjekt im ParentObject Member der WDF_OBJECT_ATTRIBUTES-Struktur angeben. Das übergeordnete Objekt muss ein Framework-Geräteobjekt oder ein Objekt sein, dessen Übergeordnete Kette zu einem Framework-Geräteobjekt führt. Das Framework löscht das Arbeitselementobjekt, wenn es das Geräteobjekt löscht.

Um das Arbeitselementobjekt zuvor zu löschen, kann der Treiber WdfObjectDeleteaufrufen, wie in Using Framework Work Itemsbeschrieben.

Der Treiber kann das übergeordnete Objekt einer Arbeitsaufgabe abrufen, indem WdfWorkItemGetParentObjectaufgerufen wird.

Wenn Ihr Treiber EvtCleanupCallback oder EvtDestroyCallback- Rückruffunktionen für das Arbeitselementobjekt bereitstellt, beachten Sie, dass das Framework diese Rückruffunktionen bei IRQL = PASSIVE_LEVEL aufruft.

Weitere Informationen zu Arbeitsaufgaben finden Sie unter Using Framework Work Items.

Beispiele

Im folgenden Codebeispiel wird eine WDF_OBJECT_ATTRIBUTES-Struktur initialisiert, eine WDF_WORKITEM_CONFIG Struktur initialisiert und WdfWorkItemCreateaufgerufen.

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;
}

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfworkitem.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL-	<= DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Siehe auch

WdfWorkItemEnqueue-

Freigeben über