DRIVER_DISPATCH Rückruffunktion (wdm.h)

Artikel
02/07/2025

Die Rückrufroutinedienste bieten verschiedene IRPs. Eine Liste der Funktionscodes finden Sie in den Hinweisen.

Syntax

DRIVER_DISPATCH DriverDispatch;

NTSTATUS DriverDispatch(
  [in, out] _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp
)
{...}

Parameter

[in, out] DeviceObject

Vom Aufrufer bereitgestellter Zeiger auf eine DEVICE_OBJECT Struktur. Dies ist das Geräteobjekt für das Zielgerät, das zuvor vom AddDevice Routine des Treibers erstellt wurde.

[in, out] Irp

Vom Aufrufer bereitgestellter Zeiger auf eine IRP--Struktur, die den angeforderten E/A-Vorgang beschreibt.

Rückgabewert

Wenn die Routine erfolgreich ist, muss sie STATUS_SUCCESS zurückgeben. Andernfalls muss eine der fehlerstatuswerte zurückgegeben werden, die in Ntstatus.h definiert sind.

Bemerkungen

Eingabeparameter für alle Dispatch Routinen werden in der IRP- Struktur angegeben, auf die Irpverweist. Zusätzliche Parameter werden an der zugeordneten E/A-Position des Treibers bereitgestellt, die durch die IO_STACK_LOCATION-Struktur beschrieben wird und durch Aufrufen IoGetCurrentIrpStackLocationabgerufen werden kann.

Im Allgemeinen werden alle Dispatch- Routinen in einem beliebigen Threadkontext bei IRQL = PASSIVE_LEVEL ausgeführt, es gibt jedoch Ausnahmen. Weitere Informationen finden Sie unter Dispatch Routines and IRQLs.

Weitere Informationen zu Verteilerroutinen finden Sie unter Writing Dispatch Routines. Weitere Informationen zu IRPs finden Sie unter Behandeln von IRPs.

IRP	Informationen zur Implementierung des Rückrufs
IRP_MJ_CLEANUP	Die DispatchCleanup Routine eines Treibers sollte XxxDispatchCleanup benannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry Routine des Treibers muss die Adresse der DispatchCleanup Routine in DriverObject-->MajorFunction[IRP_MJ_CLEANUP] speichern.
IRP_MJ_CLOSE	Die DispatchClose Routine eines Treibers sollte XxxDispatchClose-benannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die DispatchClose Adresse der Routine in DriverObject-->MajorFunction-[IRP_MJ_CLOSE] speichern.
IRP_MJ_CREATE	Die DispatchCreate Routine eines Treibers sollte XxxDispatchCreate benannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die DispatchCreate--Routineadresse in DriverObject-speichern –>MajorFunction[IRP_MJ_CREATE].
IRP_MJ_CREATE oder IRP_MJ_CLOSE	Ein Treiber kann eine einzelne DispatchCreateClose Routine anstelle separater DispatchCreate und DispatchClose Routinen bereitstellen. Die DispatchCreateClose Routine eines Treibers sollte Xxx-DispatchCreateClose-benannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die DispatchCreateClose--Routineadresse in DriverObject-->MajorFunction[IRP_MJ_CREATE] und in DriverObject-->MajorFunction[IRP_MJ_CLOSE] speichern.
IRP_MJ_DEVICE_CONTROL	Die DispatchDeviceControl-Routine eines Treibers sollte XxxDispatchDeviceControl-benannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry Routine des Treibers muss die Adresse des DispatchDeviceControl- Routine in DriverObject-->MajorFunction-[IRP_MJ_DEVICE_CONTROL] speichern. Das System verwendet die FILE_XXX- Flags im I/O-Steuerelementcode, um zu bestimmen, ob der IRP-Absender über die Berechtigungen zum Senden des IRP an das Geräteobjekt verfügt. Treiber für Windows Server 2003 und höhere Versionen von Windows können die IoValidateDeviceIoControlAccess Routine verwenden, um strengere Zugriffsprüfungen innerhalb DispatchDeviceControldurchzuführen.
IRP_MJ_FLUSH_BUFFERS	Die DispatchFlushBuffers Routine eines Treibers sollte XxxDispatchFlushBuffers benannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die DispatchFlushBuffers Routineadresse in DriverObject-->MajorFunction[IRP_MJ_FLUSH_BUFFERS] speichern.
IRP_MJ_INTERNAL_DEVICE_CONTROL	Die DispatchInternalDeviceControl Routine eines Treibers sollte Xxx-DispatchInternalDeviceControl-benannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die DispatchInternalDeviceControl Routineadresse in DriverObject-->MajorFunction-[IRP_MJ_INTERNAL_DEVICE_CONTROL] speichern.
IRP_MJ_PNP	Die DispatchPnP- Routine eines Treibers sollte XxxDispatchPnP benannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry Routine des Treibers muss die DispatchPnP--Routineadresse in DriverObject-->MajorFunction[IRP_MJ_PNP] speichern.
IRP_MJ_POWER	Die DispatchPower Routine eines Treibers sollte XxxDispatchPowerbenannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die DispatchPower-Routineadresse in DriverObject-->MajorFunction-[IRP_MJ_POWER] speichern.
IRP_MJ_QUERY_INFORMATION	Die DispatchQueryInformation Routine eines Treibers sollte XxxDispatchQueryInformationbenannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry Routine des Treibers muss die Adresse der DispatchQueryInformation- Routine in DriverObject-->MajorFunction[IRP_MJ_QUERY_INFORMATION] speichern.
IRP_MJ_READ	Die DispatchRead-Routine eines Treibers sollte XxxDispatchRead-benannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry Routine des Treibers muss die Adresse der DispatchRead- Routine in DriverObject-->MajorFunction-[IRP_MJ_READ] speichern.
IRP_MJ_READ oder IRP_MJ_WRITE	Ein Treiber kann eine einzelne DispatchReadWrite- Routine anstelle separater DispatchRead- und DispatchWrite-Routinen bereitstellen. Die DispatchReadWrite-Routine eines Treibers sollte Xxx-DispatchReadWrite-benannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die DispatchReadWrite--Routineadresse in DriverObject-->MajorFunction-[IRP_MJ_READ] und in DriverObject-->MajorFunction[IRP_MJ_WRITE] speichern.
IRP_MJ_SET_INFORMATION	Die DispatchSetInformation Routine eines Treibers sollte XxxDispatchSetInformationbenannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry Routine des Treibers muss die Adresse der DispatchSetInformation- Routine in DriverObject-->MajorFunction[IRP_MJ_SET_INFORMATION] speichern.
IRP_MJ_SHUTDOWN	Die DispatchShutdown Routine eines Treibers sollte XxxDispatchShutdown-benannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die DispatchShutdown--Routineadresse in DriverObject-->MajorFunction-[IRP_MJ_SHUTDOWN] speichern. Um IRP_MJ_SHUTDOWN Anforderungen zu erhalten, muss ein Treiber darüber hinaus IoRegisterShutdownNotification oder IoRegisterLastChanceShutdownNotification aufrufen, um seine DispatchShutdown Routine beim System zu registrieren.
IRP_MJ_SYSTEM_CONTROL	Die DispatchSystemControl Routine eines Treibers sollte XxxDispatchSystemControl-benannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die DispatchSystemControl--Routineadresse in DriverObject-->MajorFunction-[IRP_MJ_SYSTEM_CONTROL] speichern.
IRP_MJ_WRITE	Die DispatchWrite-Routine eines Treibers sollte XxxDispatchWrite-benannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry Routine des Treibers muss die Adresse der DispatchWrite Routine in DriverObject-->MajorFunction-[IRP_MJ_WRITE] speichern.

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 DispatchCleanup- Rückrufroutine definieren möchten, die MyDispatchCleanupheißt, verwenden Sie den DRIVER_DISPATCH Typ, wie in diesem Codebeispiel gezeigt:

DRIVER_DISPATCH MyDispatchCleanup;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
NTSTATUS
  MyDispatchCleanup(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp
    )
  {
      // Function body
  }

Der DRIVER_DISPATCH Funktionstyp wird in der Wdm.h-Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie Ihrer Funktionsdefinition the_Use_decl_annotations_annotation hinzufügen. The_Use_decl_annotations_annotation stellt sicher, dass die Anmerkungen, die auf den Funktionstyp DRIVER_DISPATCH in der Headerdatei angewendet werden, verwendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für WDM-Treiber. Informationen zu Use_decl_annotationsfinden Sie unter Annotating Function Behavior.

Anforderungen

Anforderung	Wert
Zielplattform-	Desktop
Header-	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL-	Aufgerufen bei PASSIVE_LEVEL (siehe Abschnitt "Hinweise").

Freigeben über