WdfDpcCreate-Funktion (wdfdpc.h)

Artikel
02/27/2024

[Gilt nur für KMDF]

Die WdfDpcCreate-Methode erstellt ein Framework-DPC-Objekt und registriert eine EvtDpcFunc-Rückruffunktion .

Syntax

NTSTATUS WdfDpcCreate(
  [in]  PWDF_DPC_CONFIG        Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFDPC                 *Dpc
);

Parameter

[in] Config

Ein Zeiger auf eine aufruferseitig zugeordnete WDF_DPC_CONFIG-Struktur .

[in] Attributes

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_OBJECT_ATTRIBUTES Struktur, die Attribute für das neue DPC-Objekt angibt.

[out] Dpc

Ein Zeiger auf einen Speicherort, der ein Handle für das neue Framework-DPC-Objekt empfängt.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde angegeben.
STATUS_INSUFFICIENT_RESOURCES	Ein DPC-Objekt konnte nicht zugeordnet werden.
STATUS_WDF_PARENT_NOT_SPECIFIED	In der WDF_OBJECT_ATTRIBUTES-Struktur wurde kein übergeordnetes Objekt angegeben.
STATUS_INVALID_DEVICE_REQUEST	Das ParentObject-Element der WDF_OBJECT_ATTRIBUTES-Struktur verweist nicht auf ein Framework-Geräteobjekt oder ein Objekt, dessen Kette von übergeordneten Elementen zu einem Framework-Geräteobjekt führt.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	Der AutomaticSerialization-Member der WDF_DPC_CONFIG-Struktur ist auf TRUE festgelegt, die Ausführungsebene des übergeordneten Objekts ist jedoch auf WdfExecutionLevelPassive festgelegt.

Eine Liste mit anderen Rückgabewerten, die von der WdfDpcCreate-Methode möglicherweise zurückgegeben werden, finden Sie unter Fehler beim Erstellen von Frameworkobjekten.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Hinweise

Ein Treiber ruft in der Regel WdfDpcCreate aus seiner EvtDriverDeviceAdd-Rückruffunktion auf.

Wenn ein Treiber ein DPC-Objekt erstellt, muss er ein übergeordnetes Objekt im ParentObject-Element der WDF_OBJECT_ATTRIBUTES-Struktur angeben. Das übergeordnete Objekt kann ein Framework-Geräteobjekt oder ein beliebiges Objekt sein, dessen Kette von übergeordneten Elementen zu einem Framework-Geräteobjekt führt. Das Framework löscht das DPC-Objekt, wenn es das Geräteobjekt löscht.

Beim Aufrufen von WdfDpcCreate wird ein Framework-DPC-Objekt erstellt und eine EvtDpcFunc-Rückruffunktion registriert. Um die Ausführung der Rückruffunktion zu planen, muss der Treiber WdfDpcEnqueue aufrufen.

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

Weitere Informationen zur Verwendung von DPC-Objekten finden Sie unter Servicing an Interrupt.

Beispiele

Im folgenden Codebeispiel wird eine WDF_DPC_CONFIG_INIT-Struktur initialisiert und anschließend ein DPC-Objekt erstellt.

WDF_DPC_CONFIG dpcConfig;
WDF_OBJECT_ATTRIBUTES dpcAttributes;
NTSTATUS status;

WDF_DPC_CONFIG_INIT(
                    &dpcConfig,
                    MyEvtDpcFunc
                    );
dpcConfig.AutomaticSerialization = TRUE;
WDF_OBJECT_ATTRIBUTES_INIT(&dpcAttributes);
dpcAttributes.ParentObject = pDevExt->WdfDevice;
status = WdfDpcCreate(
                      &dpcConfig,
                      &dpcAttributes,
                      &pDevExt->CompleteWriteDpc
                      );
if (!NT_SUCCESS(status)) {
    return status;
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
Kopfzeile	wdfdpc.h (include Wdf.h)
Bibliothek	Wdf01000.sys (siehe Versionsverwaltung der Frameworkbibliothek).)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)