KDEFERRED_ROUTINE Rückruffunktion (wdm.h)

Artikel
02/07/2025

Die Rückrufroutine führt Aktionen aus, nachdem ein InterruptService- zurückgegeben wurde, eines DPC-Threads,

Die CustomDpc Routine beendet die Wartung eines E/A-Vorgangs, nachdem eine InterruptService- Routine zurückgegeben wurde.

Die CustomThreadedDpc Routine führt die Aktion eines DPC-Threads aus. Das System führt diese Routine aus, wenn der Thread-DPC ausgeführt wird.

Die CustomTimerDpc- Routine wird nach Ablauf des Zeitintervalls eines Timerobjekts ausgeführt.

Syntax

KDEFERRED_ROUTINE KdeferredRoutine;

void KdeferredRoutine(
  [in]           _KDPC *Dpc,
  [in, optional] PVOID DeferredContext,
  [in, optional] PVOID SystemArgument1,
  [in, optional] PVOID SystemArgument2
)
{...}

Parameter

[in] Dpc

Vom Aufrufer bereitgestellter Zeiger auf eine KDPC--Struktur, die das DPC-Objekt darstellt, das dieser Rückrufroutine zugeordnet ist.

[in, optional] DeferredContext

Für CustomDpc-wird ein vom Aufrufer bereitgestellter Zeiger auf treiberdefinierte Kontextinformationen angegeben, die in einem vorherigen Aufruf von KeInitializeDpcangegeben wurden.

Gibt für CustomThreadedDpc-treiberdefinierte Kontextinformationen an. Beim Initialisieren des DPC-Objekts hat der Treiber diesen Wert als DeferredContext Parameter für KeInitializeThreadedDpcangegeben.

Vom Aufrufer bereitgestellter Zeiger auf eine KDPC--Struktur, die das diesem CustomTimerDpc Routine zugeordnete DPC-Objekt darstellt.

[in, optional] SystemArgument1

Vom Anrufer bereitgestellte Zeiger auf vom Treiber bereitgestellte Informationen, die in einem vorherigen Aufruf von KeInsertQueueDpcangegeben wurden. Wenn der DPC der DPC-Warteschlange hinzugefügt wurde, hat der Treiber diesen Wert als SystemArgument1 Parameter für KeInsertQueueDpcangegeben.

Für CustomTimerDpc-wird dieser Wert nicht verwendet.

[in, optional] SystemArgument2

Gibt treiberdefinierte Kontextinformationen an. Wenn der DPC der DPC-Warteschlange hinzugefügt wurde, hat der Treiber diesen Wert als SystemArgument2-parameter KeInsertQueueDpcangegeben.

Für CustomTimerDpc-wird dieser Wert nicht verwendet.

Rückgabewert

Nichts

Bemerkungen

Um ein DPC-Objekt zu erstellen und eine CustomDpc Routine für dieses Objekt zu registrieren, muss ein Treiber KeInitializeDpcaufrufen. (Wenn Sie nur eine DPC-Routine benötigen, können Sie eine DpcForIsr- Routine und das vom System zugewiesene DPC-Objekt verwenden.)

Um eine CustomDpc Routine für die Ausführung in die Warteschlange zu stellen, muss die InterruptService-Routine eines TreibersKeInsertQueueDpcaufrufen.

Mindestens ein CustomDpc Routinen kann anstelle oder in Verbindung mit einer DpcForIsr- Routine verwendet werden. Ein Treiber, der mehrere interne IRP-Warteschlangen verwaltet, liefert in der Regel eine CustomDpc Routine für jede Warteschlange. Jede CustomDpc Routine ist in der Regel für mindestens die folgenden Aufgaben verantwortlich:

Abschließen des I/O-Vorgangs, der vom aktuellen IRP beschrieben wird.
Dequeuing the next IRP from one of the driver's IRP queues. (Treiber, die die vom System bereitgestellte IRP-Warteschlange zusammen mit einem StartIo Routineanruf IoStartNextPacket.)
Festlegen des E/A-Statusblocks im aktuellen IRP und Aufrufen IoCompleteRequest- für die abgeschlossene Anforderung.

Eine CustomDpc- Routine kann auch einen fehlgeschlagenen Vorgang wiederholen oder die nächste Übertragung für eine große E/A-Anforderung einrichten, die in kleinere Teile unterteilt wurde.

Weitere Informationen zu CustomDpc Routinen finden Sie unter DPC Objects and DPCs.

Ein Treiber registriert einen CustomThreadedDpc- für ein DPC-Objekt, indem KeInitializeThreadedDpcaufgerufen wird. Rufen Sie KeInsertQueueDpcauf, um die DPC-Warteschlange tatsächlich der DPC-Warteschlange hinzuzufügen, damit die CustomThreadedDpc- ausgeführt wird.

Weitere Informationen zur Verwendung von CustomThreadedDpc Routinen finden Sie unter Einführung in Threaded DPCs.

Eine CustomThreadedDpc Routine kann bei IRQL = DISPATCH_LEVEL ausgeführt werden, oder sie kann bei IRQL = PASSIVE_LEVEL in einem Echtzeitthread ausgeführt werden.

Um ein DPC-Objekt zu erstellen und eine CustomTimerDpc-Routine für dieses Objekt zu registrieren, muss ein Treiber KeInitializeDpcaufrufen.

Um eine CustomTimerDpc-Routine für die Ausführung in die Warteschlange zu stellen, muss eine Treiberroutine KeSetTimer oder KeSetTimerExaufrufen, wobei ein DPC-Objektzeiger bereitgestellt wird, der von KeInitializeDpczurückgegeben wird. Das System ruft die CustomTimerDpc Routine auf, wenn das Zeitgeberintervall abläuft.

Weitere Informationen zu CustomTimerDpc Routinen finden Sie unter Timer Objects and DPCs.

Beispiele

Um eine Rückrufroutine zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückrufroutine identifiziert. Windows stellt eine Reihe von Rückruffunktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Wenn Sie beispielsweise eine CustomDpc- Rückrufroutine definieren möchten, die MyCustomDpcbenannt ist, verwenden Sie den KDEFERRED_ROUTINE Typ wie in diesem Codebeispiel gezeigt:

KDEFERRED_ROUTINE MyCustomDpc;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
VOID
  MyCustomDpc(
    struct _KDPC  *Dpc,
    PVOID  DeferredContext,
    PVOID  SystemArgument1,
    PVOID  SystemArgument2
    )
  {
      // Function body
  }