WdfDmaTransactionInitializeUsingRequest, fonction (wdfdmatransaction.h)

Article
02/27/2024

[S’applique uniquement à KMDF]

La méthode WdfDmaTransactionInitializeUsingRequest initialise une transaction DMA spécifiée à l’aide des paramètres d’une demande d’E/S spécifiée.

Syntaxe

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

Paramètres

[in] DmaTransaction

Handle pour un objet de transaction DMA que le pilote a obtenu à partir d’un appel précédent à WdfDmaTransactionCreate.

[in] Request

Handle d’un objet de requête d’infrastructure.

[in] EvtProgramDmaFunction

Pointeur vers la fonction de rappel d’événement EvtProgramDma du pilote.

[in] DmaDirection

Valeur de type WDF_DMA_DIRECTION qui spécifie le sens du transfert DMA.

Valeur retournée

WdfDmaTransactionInitializeUsingRequest retourne STATUS_SUCCESS si l’opération réussit. Sinon, la méthode peut retourner l’une des valeurs décrites dans la section Valeurs de retour de WdfDmaTransactionInitialize.

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

La méthode WdfDmaTransactionInitializeUsingRequest prépare une opération DMA pour l’exécution, en effectuant des opérations d’initialisation telles que la configuration de la liste de points/regroupements d’une transaction. Une fois que votre pilote a appelé WdfDmaTransactionInitializeUsingRequest, le pilote doit appeler WdfDmaTransactionExecute.

Le pilote peut appeler WdfRequestGetParameters pour obtenir le type d’une requête. La valeur que le pilote spécifie pour le paramètre DmaDirection doit être appropriée pour le type de requête, comme suit :

La valeur DmaDirection doit être WdfDmaDirectionReadFromDevice si :
- Le type de requête est WdfRequestTypeRead
- Le type de requête est WdfRequestTypeDeviceControl ou WdfRequestTypeDeviceControlInternal et le code de contrôle d’E/S spécifie un type de transfert de METHOD_OUT_DIRECT
La valeur DmaDirection doit être WdfDmaDirectionWriteToDevice si :
- Le type de requête est WdfRequestTypeWrite
- Le type de requête est WdfRequestTypeDeviceControl ou WdfRequestTypeDeviceControlInternal et le code de contrôle d’E/S spécifie un type de transfert de METHOD_IN_DIRECT

Pour plus d’informations sur les types de transfert pour les codes de contrôle d’E/S, consultez Définition des codes de contrôle d’E/S.

Les pilotes basés sur l’infrastructure appellent généralement WdfDmaTransactionInitializeUsingRequest à partir d’une fonction de rappel d’événement de file d’E/S.

Votre pilote doit appeler WdfDmaTransactionInitializeUsingRequest si vous créez une transaction DMA basée sur les informations contenues dans un objet de demande d’infrastructure. Utilisez WdfDmaTransactionInitialize si vous créez une transaction DMA qui n’est pas basée sur un objet de requête.

Si la mémoire tampon décrite par l’objet de requête est supérieure à la longueur de transfert maximale spécifiée par votre pilote lorsqu’il a appelé WdfDmaEnablerCreate ou WdfDmaTransactionSetMaximumLength, l’infrastructure décompose la transaction en plusieurs transferts.

Pour plus d’informations sur les transactions DMA, consultez Création et initialisation d’une transaction DMA.

Exemples

Pour obtenir un exemple de code qui utilise WdfDmaTransactionInitializeUsingRequest, consultez WdfDmaTransactionExecute.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfdmatransaction.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (consultez Gestion de version de la bibliothèque d’infrastructure.)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DeferredRequestCompleted(kmdf),DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)