Función WdfDmaTransactionInitializeUsingRequest (wdfdmatransaction.h)

Artículo
08/08/2023

[Solo se aplica a KMDF]

El método WdfDmaTransactionInitializeUsingRequest inicializa una transacción DMA especificada mediante los parámetros de una solicitud de E/S especificada.

Sintaxis

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

Parámetros

[in] DmaTransaction

Identificador de un objeto de transacción DMA que el controlador obtuvo de una llamada anterior a WdfDmaTransactionCreate.

[in] Request

Identificador de un objeto de solicitud de marco.

[in] EvtProgramDmaFunction

Puntero a la función de devolución de llamada de eventos EvtProgramDma del controlador.

[in] DmaDirection

Valor con tipo WDF_DMA_DIRECTION que especifica la dirección de la transferencia DMA.

Valor devuelto

WdfDmaTransactionInitializeUsingRequest devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, el método podría devolver uno de los valores descritos en la sección Valores devueltos de WdfDmaTransactionInitialize.

Este método también podría devolver otros valores NTSTATUS.

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Comentarios

El método WdfDmaTransactionInitializeUsingRequest prepara una operación DMA para su ejecución, realizando operaciones de inicialización como la configuración de la lista de dispersión y recopilación de una transacción. Después de que el controlador llame a WdfDmaTransactionInitializeUsingRequest, el controlador debe llamar a WdfDmaTransactionExecute.

El controlador puede llamar a WdfRequestGetParameters para obtener el tipo de una solicitud. El valor que el controlador especifica para el parámetro DmaDirection debe ser adecuado para el tipo de solicitud, como se indica a continuación:

El valor DmaDirection debe ser WdfDmaDirectionReadFromDevice si:
- El tipo de solicitud es WdfRequestTypeRead
- El tipo de solicitud es WdfRequestTypeDeviceControl o WdfRequestTypeDeviceControlInternal y el código de control de E/S especifica un tipo de transferencia de METHOD_OUT_DIRECT
El valor DmaDirection debe ser WdfDmaDirectionWriteToDevice si:
- El tipo de solicitud es WdfRequestTypeWrite.
- El tipo de solicitud es WdfRequestTypeDeviceControl o WdfRequestTypeDeviceControlInternal y el código de control de E/S especifica un tipo de transferencia de METHOD_IN_DIRECT

Para obtener más información sobre los tipos de transferencia para los códigos de control de E/S, vea Definición de códigos de control de E/S.

Normalmente, los controladores basados en marcos llaman a WdfDmaTransactionInitializeUsingRequest desde dentro de una función de devolución de llamada de evento de cola de E/S.

El controlador debe llamar a WdfDmaTransactionInitializeUsingRequest si va a crear una transacción DMA basada en la información que contiene un objeto de solicitud de marco. Use WdfDmaTransactionInitialize si va a crear una transacción DMA que no se basa en un objeto de solicitud.

Si el búfer que describe el objeto de solicitud es mayor que la longitud máxima de transferencia que el controlador especificó cuando llamó a WdfDmaEnablerCreate o WdfDmaTransactionSetMaximumLength, el marco divide la transacción en varias transferencias.

Para obtener más información sobre las transacciones de DMA, consulte Creación e inicialización de una transacción DMA.

Ejemplos

Para obtener un ejemplo de código que usa WdfDmaTransactionInitializeUsingRequest, vea WdfDmaTransactionExecute.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Encabezado	wdfdmatransaction.h (incluya Wdf.h)
Library	Wdf01000.sys (consulte Control de versiones de la biblioteca de marcos).
IRQL	<=DISPATCH_LEVEL
Reglas de cumplimiento de DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)