DRIVER_DISPATCH Rückruffunktion (wdm.h)
Die Rückrufroutinedienste bieten verschiedene IRPs. Eine Liste der Funktionscodes finden Sie unter Hinweise.
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 von der 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 einer der In Ntstatus.h definierten Fehlerwerte status zurückgegeben werden.
Hinweise
Eingabeparameter für alle Dispatch-Routinen werden in der IRP-Struktur bereitgestellt, auf die von Irp verwiesen wird. Zusätzliche Parameter werden am zugeordneten E/A-Stapelspeicherort des Treibers bereitgestellt, der von der IO_STACK_LOCATION-Struktur beschrieben wird und durch Aufrufen von IoGetCurrentIrpStackLocation abgerufen werden kann.
Im Allgemeinen werden alle Dispatch-Routinen in einem beliebigen Threadkontext unter IRQL = PASSIVE_LEVEL ausgeführt, es gibt jedoch Ausnahmen. Weitere Informationen finden Sie unter Dispatch Routines and IRQLs.
Weitere Informationen zu Dispatchroutinen finden Sie unter Schreiben von Dispatch-Routinen. Weitere Informationen zu IRPs finden Sie unter Behandeln von IRPs.
| IRP | Informationen zum Implementieren des Rückrufs |
|---|---|
| IRP_MJ_CLEANUP | Die DispatchCleanup-Routine eines Treibers sollte XxxDispatchCleanup heißen, 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 heißen, wobei Xxx ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die Adresse der DispatchClose-Routine in DriverObject-MajorFunction>[IRP_MJ_CLOSE] speichern. |
| IRP_MJ_CREATE | Die DispatchCreate-Routine eines Treibers sollte XxxDispatchCreate heißen, wobei Xxx ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die Adresse der DispatchCreate-Routine in DriverObject-MajorFunction>[IRP_MJ_CREATE] speichern. |
| 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 XxxDispatchCreateClose heißen, wobei Xxx ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die Adresse der DispatchCreateClose-Routine in DriverObject-MajorFunction>[IRP_MJ_CREATE] und inDriverObject-MajorFunction>[IRP_MJ_CLOSE] speichern. |
| IRP_MJ_DEVICE_CONTROL | Die DispatchDeviceControl-Routine eines Treibers sollte XxxDispatchDeviceControl heißen, wobei Xxx ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die Adresse der DispatchDeviceControl-Routine in DriverObject-MajorFunction>[IRP_MJ_DEVICE_CONTROL] speichern. Das System verwendet die FILE_XXX-Flags im E/A-Steuerungscode, 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 in DispatchDeviceControl durchzuführen. |
| IRP_MJ_FLUSH_BUFFERS | Die DispatchFlushBuffers-Routine eines Treibers sollte XxxDispatchFlushBuffers heißen, wobei Xxx ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die Adresse der DispatchFlushBuffers-Routine in DriverObject-MajorFunction>[IRP_MJ_FLUSH_BUFFERS] speichern. |
| IRP_MJ_INTERNAL_DEVICE_CONTROL | Die DispatchInternalDeviceControl-Routine eines Treibers sollte XxxDispatchInternalDeviceControl heißen, wobei Xxx ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die Adresse der DispatchInternalDeviceControl-Routine in DriverObject-MajorFunction>[IRP_MJ_INTERNAL_DEVICE_CONTROL] speichern. |
| IRP_MJ_PNP | Die DispatchPnP-Routine eines Treibers sollte XxxDispatchPnP heißen, wobei Xxx ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die Adresse der DispatchPnP-Routine in DriverObject-MajorFunction>[IRP_MJ_PNP] speichern. |
| IRP_MJ_POWER | Die DispatchPower-Routine eines Treibers sollte XxxDispatchPower heißen, wobei Xxx ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die Adresse der DispatchPower-Routine in DriverObject-MajorFunction>[IRP_MJ_POWER] speichern. |
| IRP_MJ_QUERY_INFORMATION | Die DispatchQueryInformation-Routine eines Treibers sollte XxxDispatchQueryInformation heißen, 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 heißen, 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 XxxDispatchReadWrite heißen, wobei Xxx ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die Adresse der DispatchReadWrite-Routine in DriverObject-MajorFunction>[IRP_MJ_READ] und in DriverObject-MajorFunction>[IRP_MJ_WRITE] speichern. |
| IRP_MJ_SET_INFORMATION | Die DispatchSetInformation-Routine eines Treibers sollte XxxDispatchSetInformation heißen, 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 heißen, wobei Xxx ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die Adresse der DispatchShutdown-Routine in DriverObject-MajorFunction>[IRP_MJ_SHUTDOWN] speichern. Zum Empfangen IRP_MJ_SHUTDOWN Anforderungen muss ein Treiber außerdem IoRegisterShutdownNotification oder IoRegisterLastChanceShutdownNotification aufrufen, um seine DispatchShutdown-Routine beim System zu registrieren. |
| IRP_MJ_SYSTEM_CONTROL | Die DispatchSystemControl-Routine eines Treibers sollte XxxDispatchSystemControl heißen, wobei Xxx ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die Adresse der DispatchSystemControl-Routine in DriverObject-MajorFunction>[IRP_MJ_SYSTEM_CONTROL] speichern. |
| IRP_MJ_WRITE | Die DispatchWrite-Routine eines Treibers sollte XxxDispatchWrite heißen, 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 bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.
Um beispielsweise eine DispatchCleanup-Rückrufroutine mit dem Namen MyDispatchCleanupzu definieren, verwenden Sie den typ DRIVER_DISPATCH, 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 ist in der Headerdatei Wdm.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie Ihrer Funktionsdefinition the_Use_decl_annotations_annotation hinzu. The_Use_decl_annotations_annotation stellt sicher, dass die Anmerkungen verwendet werden, die auf den DRIVER_DISPATCH Funktionstyp in der Headerdatei angewendet 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_annotations finden Sie unter Verhalten von Funktionen mit Anmerkungen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Desktop |
| Header | wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | Wird bei PASSIVE_LEVEL aufgerufen (siehe Abschnitt Hinweise). |