Funzione WdfDmaTransactionInitializeUsingRequest (wdfdmatransaction.h)

Articolo
02/29/2024

[Si applica solo a KMDF]

Il metodo WdfDmaTransactionInitializeUsingRequest inizializza una transazione DMA specificata utilizzando i parametri di una richiesta di I/O specificata.

Sintassi

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

Parametri

[in] DmaTransaction

Handle per un oggetto transazione DMA ottenuto dal driver da una chiamata precedente a WdfDmaTransactionCreate.

[in] Request

Handle per un oggetto richiesta del framework.

[in] EvtProgramDmaFunction

Puntatore alla funzione di callback dell'evento EvtProgramDma del driver.

[in] DmaDirection

Valore tipizzato WDF_DMA_DIRECTION che specifica la direzione del trasferimento DMA.

Valore restituito

WdfDmaTransactionInitializeUsingRequest restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, il metodo potrebbe restituire uno dei valori descritti nella sezione Valori restituiti di WdfDmaTransactionInitialize.

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Commenti

Il metodo WdfDmaTransactionInitializeUsingRequest prepara un'operazione DMA per l'esecuzione, eseguendo operazioni di inizializzazione come la configurazione dell'elenco a dispersione/raccolta di una transazione. Dopo che il driver chiama WdfDmaTransactionInitializeUsingRequest, il driver deve chiamare WdfDmaTransactionExecute.

Il driver può chiamare WdfRequestGetParameters per ottenere il tipo di una richiesta. Il valore specificato dal driver per il parametro DmaDirection deve essere appropriato per il tipo di richiesta, come indicato di seguito:

Il valore DmaDirection deve essere WdfDmaDirectionReadFromDevice se:
- Il tipo di richiesta è WdfRequestTypeRead
- Il tipo di richiesta è WdfRequestTypeDeviceControl o WdfRequestTypeDeviceControlInternal e il codice di controllo I/O specifica un tipo di trasferimento di METHOD_OUT_DIRECT
Il valore DmaDirection deve essere WdfDmaDirectionWriteToDevice se:
- Il tipo di richiesta è WdfRequestTypeWrite
- Il tipo di richiesta è WdfRequestTypeDeviceControl o WdfRequestTypeDeviceControlInternal e il codice di controllo I/O specifica un tipo di trasferimento di METHOD_IN_DIRECT

Per altre informazioni sui tipi di trasferimento per i codici di controllo di I/O, vedere Definizione dei codici di controllo di I/O.

I driver basati su framework in genere chiamano WdfDmaTransactionInitializeUsingRequest dall'interno di una funzione di callback degli eventi della coda I/O.

Il driver deve chiamare WdfDmaTransactionInitializeUsingRequest se si sta creando una transazione DMA basata su informazioni contenute in un oggetto richiesta framework. Utilizzare WdfDmaTransactionInitialize se si sta creando una transazione DMA non basata su un oggetto richiesta.

Se il buffer descritto dall'oggetto richiesta è maggiore della lunghezza massima di trasferimento specificata dal driver quando viene chiamato WdfDmaEnablerCreate o WdfDmaTransactionSetMaximumLength, il framework suddivide la transazione in più trasferimenti.

Per altre informazioni sulle transazioni DMA, vedere Creazione e inizializzazione di una transazione DMA.

Esempio

Per un esempio di codice che usa WdfDmaTransactionInitializeUsingRequest, vedere WdfDmaTransactionExecute.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Intestazione	wdfdmatransaction.h (include Wdf.h)
Libreria	Wdf01000.sys (vedere Controllo delle versioni della libreria framework).
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf),RequestCompletedLocal(kmdf)