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 von der AddDevice-Routine des Treibers erstellt wurde.

[in, out] Irp

Vom Aufrufer bereitgestellter Zeiger auf eine IRP-Struktur . Irp entspricht dem Wert des CurrentIrp-Members von DeviceObject , als die Rückrufroutine registriert wurde.

[in] MapRegisterBase

Im Fall von AdapterControl ist dies ein vom Aufrufer bereitgestellter undurchsichtiger Wert, der die Kartenregister darstellt, die das System für diesen Übertragungsvorgang zugewiesen hat. Der Treiber übergibt diesen Wert an FlushAdapterBuffers, FreeMapRegisters und MapTransfer.

Im Fall von ControllerControl wird dies nicht verwendet.

[in] Context

Vom Aufrufer bereitgestellter Zeiger auf vom Treiber definierte Kontextinformationen, die in einem vorherigen Aufruf von AllocateAdapterChannel angegeben wurden.

Rückgabewert

Die Routine muss einen der von der IO_ALLOCATION_ACTION-Enumeration definierten Werte zurückgeben. Treiber von Bus-master-Geräten geben entweder DeallocateObject oder DeallocateObjectKeepRegisters zurück. Treiber, die System-DMA verwenden, geben KeepObject zurück.

Hinweise

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 der AdapterControl-Routine anzugeben. Wenn der Adapter frei ist, ruft das System die AdapterControl-Routine auf.

Wenn AdapterControl von einer StartIo-Routine registriert wurde, wird garantiert, dass der Irp-Parameter auf den IRP verweist, der derzeit von der StartIo-Routine verarbeitet wird. Andernfalls müssen Treiber das CurrentIrp-Element der Geräteobjektstruktur festlegen, bevor Sie AllocateAdapterChannel aufrufen.

Ausführliche Informationen zum Implementieren einer AdapterControl-Routine finden Sie unter Schreiben von AdapterControl-Routinen.

Die ControllerControl-Routine eines Treibers wird in einem beliebigen Threadkontext unter 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 der 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 Schreiben von ControllerControl-Routinen. Weitere Informationen finden Sie unter Controllerobjekte.

Der DRIVER_CONTROL Funktionstyp ist in der Wdm.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie die _Use_decl_annotations_ Anmerkung ihrer Funktionsdefinition hinzu. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den DRIVER_CONTROL 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 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 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 AdapterControl-Rückrufroutine mit dem Namen MyAdapterControlzu definieren, verwenden Sie den typ DRIVER_CONTROL, 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 (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Wird bei DISPATCH_LEVEL aufgerufen.

Weitere Informationen

AllocateAdapterChannel