Функция WdfDmaTransactionInitializeUsingRequest (wdfdmatransaction.h)

Статья
08/08/2023

[Применяется только к KMDF]

Метод WdfDmaTransactionInitializeUsingRequest инициализирует указанную транзакцию DMA с помощью параметров указанного запроса ввода-вывода.

Синтаксис

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

Параметры

[in] DmaTransaction

Дескриптор объекта транзакции DMA, полученного драйвером при предыдущем вызове WdfDmaTransactionCreate.

[in] Request

Дескриптор объекта запроса платформы.

[in] EvtProgramDmaFunction

Указатель на функцию обратного вызова события EvtProgramDma драйвера.

[in] DmaDirection

WDF_DMA_DIRECTION типизированное значение, указывающее направление передачи DMA.

Возвращаемое значение

WdfDmaTransactionInitializeUsingRequest возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае метод может вернуть одно из значений, описанных в разделе Возвращаемые значения статьи WdfDmaTransactionInitialize.

Этот метод также может возвращать другие значения NTSTATUS.

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Метод WdfDmaTransactionInitializeUsingRequest подготавливает операцию DMA к выполнению, выполняя операции инициализации, такие как настройка точечных и сборных списков транзакций. После вызова драйвером WdfDmaTransactionInitializeUsingRequest драйвер должен вызвать WdfDmaTransactionExecute.

Драйвер может вызвать WdfRequestGetParameters , чтобы получить тип запроса. Значение, указанное драйвером для параметра DmaDirection , должно соответствовать типу запроса следующим образом:

Значение DmaDirection должно иметь значение WdfDmaDirectionReadFromDevice, если:
- Тип запроса — WdfRequestTypeRead.
- Тип запроса — WdfRequestTypeDeviceControl или WdfRequestTypeDeviceControlInternal , а код элемента управления вводом-выводом задает тип передачи METHOD_OUT_DIRECT
Значение DmaDirection должно иметь значение WdfDmaDirectionWriteToDevice, если:
- Тип запроса — WdfRequestTypeWrite.
- Тип запроса — WdfRequestTypeDeviceControl или WdfRequestTypeDeviceControlInternal , а код элемента управления вводом-выводом задает тип передачи METHOD_IN_DIRECT

Дополнительные сведения о типах передачи для кодов элементов управления вводом-выводом см. в разделе Определение кодов элементов управления ввода-вывода.

Драйверы на основе платформы обычно вызывают WdfDmaTransactionInitializeUsingRequest из функции обратного вызова событий очереди ввода-вывода.

Драйвер должен вызвать WdfDmaTransactionInitializeUsingRequest , если вы создаете транзакцию DMA, основанную на сведениях, содержащихся в объекте запроса платформы. Используйте WdfDmaTransactionInitialize , если вы создаете транзакцию DMA, которая не основана на объекте запроса.

Если буфер, описываемый объектом запроса, больше максимальной длины передачи, указанной драйвером при вызове WdfDmaEnablerCreate или WdfDmaTransactionSetMaximumLength, платформа разбивает транзакцию на несколько передач.

Дополнительные сведения о транзакциях DMA см. в статье Создание и инициализация транзакции DMA.

Примеры

Пример кода, в котором используется WdfDmaTransactionInitializeUsingRequest, см. в разделе WdfDmaTransactionExecute.

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Верхняя часть	wdfdmatransaction.h (включая Wdf.h)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки платформы).
IRQL	<=DISPATCH_LEVEL
Правила соответствия DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)