DRIVER_CONTROL Rückruffunktion (wdm.h)
Diese Routine startet eine DMA-Datenübertragung oder einen Datenübertragungsvorgang.
Syntax
DRIVER_CONTROL DriverControl;
IO_ALLOCATION_ACTION DriverControl(
[in] _DEVICE_OBJECT *DeviceObject,
[in, out] _IRP *Irp,
[in] PVOID MapRegisterBase,
[in] PVOID Context
)
{...}
Parameter
[in] 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. Irp- ist gleich dem Wert des CurrentIrp- Members von DeviceObject, wenn die Rückrufroutine registriert wurde.
[in] MapRegisterBase
Bei AdapterControlist dies ein durch Aufrufer bereitgestellter undurchsichtiger Wert, der die Kartenregister darstellt, die das System für diesen Übertragungsvorgang zugewiesen hat. Der Treiber übergibt diesen Wert an FlushAdapterBuffers, FreeMapRegistersund MapTransfer.
Bei ControllerControlwird dies nicht verwendet.
[in] Context
Vom Aufrufer bereitgestellter Zeiger auf treiberdefinierte Kontextinformationen, die in einem vorherigen Aufruf von AllocateAdapterChannelangegeben wurden.
Rückgabewert
Die Routine muss einen der von der IO_ALLOCATION_ACTION Enumeration definierten Werte zurückgeben. Fahrer von Busmastergeräten geben entweder DeallocateObject oder DeallocateObjectKeepRegisterszurück; Treiber, die das System-DMA verwenden, geben KeepObjectzurück.
Bemerkungen
Um eine AdapterControl Routine für ein bestimmtes Geräteobjekt zu registrieren, muss ein Treiber IoGetDmaAdapter- aufrufen, um ein Adapterobjekt abzurufen, und dann AllocateAdapterChannel- aufrufen, um die Verwendung des Adapters anzufordern und die Adresse des AdapterControl Routine anzugeben. Wenn der Adapter kostenlos ist, ruft das System die AdapterControl Routine auf.
Wenn AdapterControl- von einer StartIo Routine registriert wurde, wird garantiert der Irp Parameter auf das IRP verweisen, das derzeit von der StartIo Routine verarbeitet wird. Andernfalls müssen Treiber das CurrentIrp Member der Geräteobjektstruktur festlegen, bevor AllocateAdapterChannelaufgerufen wird.
Ausführliche Informationen zum Implementieren einer AdapterControl Routine finden Sie unter Writing AdapterControl Routines.
Die ControllerControl-Routine eines Treibers wird in einem beliebigen Threadkontext bei IRQL = DISPATCH_LEVEL ausgeführt.
Um eine ControllerControl Routine für ein bestimmtes Geräteobjekt zu registrieren, muss ein Treiber IoCreateController- aufrufen, um ein Controllerobjekt abzurufen, und dann IoAllocateController- aufrufen, um die Verwendung des Controllers anzufordern und die Adresse des ControllerControl Routine anzugeben. Wenn der Controller frei ist, ruft das System die ControllerControl Routine auf.
Ausführliche Informationen zum Implementieren einer ControllerControl Routine finden Sie unter Writing ControllerControl Routines. Siehe auch Controllerobjekte.
Der DRIVER_CONTROL Funktionstyp wird in der Wdm.h-Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die _Use_decl_annotations_ Anmerkung hinzufügen. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen, die auf den Funktionstyp DRIVER_CONTROL 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_annotations_finden Sie unter Annotating Function Behavior.
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 AdapterControl- Rückrufroutine definieren möchten, die MyAdapterControlbenannt ist, verwenden Sie den DRIVER_CONTROL Typ, wie in diesem Codebeispiel gezeigt:
DRIVER_CONTROL MyAdapterControl;
Implementieren Sie dann Ihre Rückrufroutine wie folgt:
_Use_decl_annotations_
IO_ALLOCATION_ACTION
MyAdapterControl(
struct _DEVICE_OBJECT *DeviceObject,
struct _IRP *Irp,
PVOID MapRegisterBase,
PVOID Context
)
{
// Function body
}
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform- | Desktop |
| Header- | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL- | Wird bei DISPATCH_LEVEL aufgerufen. |