WdfDmaTransactionInitializeUsingRequest-Funktion (wdfdmatransaction.h)

Artikel
03/01/2024

[Gilt nur für KMDF]

Die WdfDmaTransactionInitializeUsingRequest-Methode initialisiert eine angegebene DMA-Transaktion mithilfe der Parameter einer angegebenen E/A-Anforderung.

Syntax

NTSTATUS WdfDmaTransactionInitializeUsingRequest(
  [in] WDFDMATRANSACTION   DmaTransaction,
  [in] WDFREQUEST          Request,
  [in] PFN_WDF_PROGRAM_DMA EvtProgramDmaFunction,
  [in] WDF_DMA_DIRECTION   DmaDirection
);

Parameter

[in] DmaTransaction

Ein Handle für ein DMA-Transaktionsobjekt, das der Treiber aus einem vorherigen Aufruf von WdfDmaTransactionCreate abgerufen hat.

[in] Request

Ein Handle für ein Frameworkanforderungsobjekt.

[in] EvtProgramDmaFunction

Ein Zeiger auf die EvtProgramDma-Ereignisrückruffunktion des Treibers.

[in] DmaDirection

Ein WDF_DMA_DIRECTION typisierter Wert, der die Richtung der DMA-Übertragung angibt.

Rückgabewert

WdfDmaTransactionInitializeUsingRequest gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die Methode möglicherweise einen der im Abschnitt Rückgabewerte von WdfDmaTransactionInitialize beschriebenen Werte zurück.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

Die WdfDmaTransactionInitializeUsingRequest-Methode bereitet einen DMA-Vorgang für die Ausführung vor, indem Initialisierungsvorgänge ausgeführt werden, z. B. das Einrichten der Scatter/Gather-Liste einer Transaktion. Nachdem Ihr Treiber WdfDmaTransactionInitializeUsingRequest aufgerufen hat, muss der Treiber WdfDmaTransactionExecute aufrufen.

Der Treiber kann WdfRequestGetParameters aufrufen, um den Typ einer Anforderung abzurufen. Der Wert, den der Treiber für den DmaDirection-Parameter angibt, muss wie folgt für den Anforderungstyp geeignet sein:

Der DmaDirection-Wert muss WdfDmaDirectionReadFromDevice sein, wenn:
- Der Anforderungstyp ist WdfRequestTypeRead.
- Der Anforderungstyp ist WdfRequestTypeDeviceControl oder WdfRequestTypeDeviceControlInternal , und der E/A-Steuerelementcode gibt einen Übertragungstyp von METHOD_OUT_DIRECT
Der DmaDirection-Wert muss WdfDmaDirectionWriteToDevice sein, wenn:
- Der Anforderungstyp ist WdfRequestTypeWrite.
- Der Anforderungstyp ist WdfRequestTypeDeviceControl oder WdfRequestTypeDeviceControlInternal , und der E/A-Steuerelementcode gibt einen Übertragungstyp von METHOD_IN_DIRECT

Weitere Informationen zu Übertragungstypen für E/A-Steuerungscodes finden Sie unter Definieren von E/A-Steuerungscodes.

Frameworkbasierte Treiber rufen in der Regel WdfDmaTransactionInitializeUsingRequest aus einer Rückruffunktion für E/A-Warteschlangenereignisse auf.

Ihr Treiber sollte WdfDmaTransactionInitializeUsingRequest aufrufen, wenn Sie eine DMA-Transaktion erstellen, die auf Informationen basiert, die ein Frameworkanforderungsobjekt enthält. Verwenden Sie WdfDmaTransactionInitialize , wenn Sie eine DMA-Transaktion erstellen, die nicht auf einem Anforderungsobjekt basiert.

Wenn der Puffer, den das Anforderungsobjekt beschreibt, größer als die maximale Übertragungslänge ist, die Ihr Treiber beim Aufrufen von WdfDmaEnablerCreate oder WdfDmaTransactionSetMaximumLength angegeben hat, unterbricht das Framework die Transaktion in mehrere Übertragungen.

Weitere Informationen zu DMA-Transaktionen finden Sie unter Erstellen und Initialisieren einer DMA-Transaktion.

Beispiele

Ein Codebeispiel, das WdfDmaTransactionInitializeUsingRequest verwendet, finden Sie unter WdfDmaTransactionExecute.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
Kopfzeile	wdfdmatransaction.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (siehe Versionierung der Frameworkbibliothek.)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)