Fungsi WdfDmaTransactionInitializeUsingRequest (wdfdmatransaction.h)

Artikel
08/08/2023

[Hanya berlaku untuk KMDF]

Metode WdfDmaTransactionInitializeUsingRequest menginisialisasi transaksi DMA tertentu dengan menggunakan parameter permintaan I/O tertentu.

Sintaks

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

Parameter

[in] DmaTransaction

Handel ke objek transaksi DMA yang diperoleh driver dari panggilan sebelumnya ke WdfDmaTransactionCreate.

[in] Request

Handel ke objek permintaan kerangka kerja.

[in] EvtProgramDmaFunction

Penunjuk ke fungsi panggilan balik peristiwa EvtProgramDma driver.

[in] DmaDirection

Nilai WDF_DMA_DIRECTION-ketik yang menentukan arah transfer DMA.

Nilai kembali

WdfDmaTransactionInitializeUsingRequest mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode mungkin mengembalikan salah satu nilai yang dijelaskan di bagian Nilai pengembalian WdfDmaTransactionInitialize.

Metode ini juga dapat mengembalikan nilai NTSTATUS lainnya.

Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.

Keterangan

Metode WdfDmaTransactionInitializeUsingRequest menyiapkan operasi DMA untuk eksekusi, dengan melakukan operasi inisialisasi seperti menyiapkan daftar sebar/kumpulkan transaksi. Setelah driver Anda memanggil WdfDmaTransactionInitializeUsingRequest, driver harus memanggil WdfDmaTransactionExecute.

Driver dapat memanggil WdfRequestGetParameters untuk mendapatkan jenis permintaan. Nilai yang ditentukan driver untuk parameter DmaDirection harus sesuai untuk jenis permintaan, sebagai berikut:

Nilai DmaDirection harus WdfDmaDirectionReadFromDevice jika:
- Jenis permintaan adalah WdfRequestTypeRead
- Jenis permintaan adalah WdfRequestTypeDeviceControl atau WdfRequestTypeDeviceControlInternal dan kode kontrol I/O menentukan jenis transfer METHOD_OUT_DIRECT
Nilai DmaDirection harus WdfDmaDirectionWriteToDevice jika:
- Jenis permintaan adalah WdfRequestTypeWrite
- Jenis permintaan adalah WdfRequestTypeDeviceControl atau WdfRequestTypeDeviceControlInternal dan kode kontrol I/O menentukan jenis transfer METHOD_IN_DIRECT

Untuk informasi selengkapnya tentang jenis transfer untuk kode kontrol I/O, lihat Menentukan Kode Kontrol I/O.

Driver berbasis kerangka kerja biasanya memanggil WdfDmaTransactionInitializeUsingRequest dari dalam fungsi panggilan balik peristiwa antrean I/O.

Driver Anda harus memanggil WdfDmaTransactionInitializeUsingRequest jika Anda membuat transaksi DMA yang didasarkan pada informasi yang berisi objek permintaan kerangka kerja. Gunakan WdfDmaTransactionInitialize jika Anda membuat transaksi DMA yang tidak didasarkan pada objek permintaan.

Jika buffer yang dijelaskan objek permintaan lebih besar dari panjang transfer maksimum yang ditentukan driver Anda ketika disebut WdfDmaEnablerCreate atau WdfDmaTransactionSetMaximumLength, kerangka kerja memecah transaksi menjadi beberapa transfer.

Untuk informasi selengkapnya tentang transaksi DMA, lihat Membuat dan Menginisialisasi Transaksi DMA.

Contoh

Untuk contoh kode yang menggunakan WdfDmaTransactionInitializeUsingRequest, lihat WdfDmaTransactionExecute.

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Header	wdfdmatransaction.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (lihat Penerapan Versi Pustaka Kerangka Kerja.)
IRQL	<=DISPATCH_LEVEL
Aturan kepatuhan DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)