WdfWorkItemCreate-Funktion (wdfworkitem.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WdfWorkItemCreate-Methode erstellt ein Framework-Arbeitselementobjekt, das anschließend der Arbeitselementwarteschlange 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 durch Aufrufen von WDF_WORKITEM_CONFIG_INIT initialisiert haben muss.

[in] Attributes

Ein Zeiger auf eine vom Aufrufer zugeordnete 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 Element des Arbeitselementobjekts ist kein Geräteobjekt oder der Vorgänger eines Geräteobjekts.
STATUS_INSUFFICIENT_RESOURCES	Es gab nicht genügend Systemressourcen, um ein Arbeitselementobjekt zu erstellen.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	Der AutomaticSerialization-Member in der WDF_WORKITEM_CONFIG Struktur, auf die der Config-Parameter verweist, ist TRUE, aber die Ausführungsebene des übergeordneten Objekts ist nicht WdfExecutionLevelPassive.
STATUS_WDF_PARENT_NOT_SPECIFIED	Der Attributes-Parameter war NULL, oder das ParentObject-Element der WDF_OBJECT_ATTRIBUTES-Struktur , die Attributes angibt, war NULL.

Hinweise

Nachdem ein Treiber WdfWorkItemCreate aufgerufen hat, um ein Arbeitselement zu erstellen, speichert er in der Regel elementspezifische Informationen im Kontextspeicher des Arbeitselementobjekts. Die EvtWorkItem-Rückruffunktion des Treibers, die die Aufgaben des Arbeitselements ausführt, kann auf diese Informationen zugreifen, um die auszuführenden Aufgaben zu ermitteln. (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 das Arbeitselement der Arbeitselementwarteschlange des Systems hinzuzufügen. Wenn ein Systemarbeitsthread verfügbar wird, entfernt der Thread das Arbeitselement aus der Warteschlange und ruft die Rückruffunktion EvtWorkItem auf.

Wenn der Treiber ein Arbeitselementobjekt erstellt, muss er ein übergeordnetes Objekt für das Arbeitselementobjekt im ParentObject-Element der WDF_OBJECT_ATTRIBUTES-Struktur angeben. Das übergeordnete Objekt muss ein Framework-Geräteobjekt oder ein Objekt sein, dessen Kette von übergeordneten Elementen 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 WdfObjectDelete aufrufen, wie unter Verwenden von Framework-Arbeitselementen beschrieben.

Der Treiber kann das übergeordnete Objekt eines Arbeitselements abrufen, indem er WdfWorkItemGetParentObject aufruft.

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

Weitere Informationen zu Arbeitselementen finden Sie unter Verwenden von Framework-Arbeitselementen.

Beispiele

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

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	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfworkitem.h (include Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Weitere Informationen

WdfWorkItemEnqueue

Freigeben über