Função WdfDmaTransactionInitializeUsingRequest (wdfdmatransaction.h)

Artigo
08/08/2023

[Aplica-se somente ao KMDF]

O método WdfDmaTransactionInitializeUsingRequest inicializa uma transação de DMA especificada usando os parâmetros de uma solicitação de E/S especificada.

Sintaxe

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

Parâmetros

[in] DmaTransaction

Um identificador para um objeto de transação DMA que o driver obteve de uma chamada anterior para WdfDmaTransactionCreate.

[in] Request

Um identificador para um objeto de solicitação de estrutura.

[in] EvtProgramDmaFunction

Um ponteiro para a função de retorno de chamada de evento EvtProgramDma do driver.

[in] DmaDirection

Um valor de tipo WDF_DMA_DIRECTION que especifica a direção da transferência de DMA.

Retornar valor

WdfDmaTransactionInitializeUsingRequest retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, o método poderá retornar um dos valores descritos na seção Valores retornados de WdfDmaTransactionInitialize.

Esse método também pode retornar outros valores NTSTATUS.

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

O método WdfDmaTransactionInitializeUsingRequest prepara uma operação de DMA para execução, executando operações de inicialização, como configurar a lista de dispersão/coleta de uma transação. Depois que o driver chamar WdfDmaTransactionInitializeUsingRequest, o driver deverá chamar WdfDmaTransactionExecute.

O driver pode chamar WdfRequestGetParameters para obter o tipo de uma solicitação. O valor que o driver especifica para o parâmetro DmaDirection deve ser apropriado para o tipo de solicitação, da seguinte maneira:

O valor DmaDirection deve ser WdfDmaDirectionReadFromDevice se:
- O tipo de solicitação é WdfRequestTypeRead
- O tipo de solicitação é WdfRequestTypeDeviceControl ou WdfRequestTypeDeviceControlInternal e o código de controle de E/S especifica um tipo de transferência de METHOD_OUT_DIRECT
O valor DmaDirection deve ser WdfDmaDirectionWriteToDevice se:
- O tipo de solicitação é WdfRequestTypeWrite
- O tipo de solicitação é WdfRequestTypeDeviceControl ou WdfRequestTypeDeviceControlInternal e o código de controle de E/S especifica um tipo de transferência de METHOD_IN_DIRECT

Para obter mais informações sobre tipos de transferência para códigos de controle de E/S, consulte Definindo códigos de controle de E/S.

Os drivers baseados em estrutura normalmente chamam WdfDmaTransactionInitializeUsingRequest de dentro de uma função de retorno de chamada de evento de fila de E/S.

Seu driver deve chamar WdfDmaTransactionInitializeUsingRequest se você estiver criando uma transação DMA baseada em informações que um objeto de solicitação de estrutura contém. Use WdfDmaTransactionInitialize se você estiver criando uma transação DMA que não se baseia em um objeto de solicitação.

Se o buffer que o objeto de solicitação descreve for maior que o comprimento máximo de transferência especificado pelo driver quando ele chamou WdfDmaEnablerCreate ou WdfDmaTransactionSetMaximumLength, a estrutura dividirá a transação em várias transferências.

Para obter mais informações sobre transações de DMA, consulte Criando e inicializando uma transação de DMA.

Exemplos

Para obter um exemplo de código que usa WdfDmaTransactionInitializeUsingRequest, consulte WdfDmaTransactionExecute.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Cabeçalho	wdfdmatransaction.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.)
IRQL	<=DISPATCH_LEVEL
Regras de conformidade de DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)