EVT_WDF_USB_READER_COMPLETION_ROUTINE fungsi panggilan balik (wdfusb.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Fungsi panggilan balik peristiwa EvtUsbTargetPipeReadComplete driver memberi tahu driver bahwa pembaca berkelanjutan telah berhasil menyelesaikan permintaan baca.

Sintaks

EVT_WDF_USB_READER_COMPLETION_ROUTINE EvtWdfUsbReaderCompletionRoutine;

void EvtWdfUsbReaderCompletionRoutine(
  [in] WDFUSBPIPE Pipe,
  [in] WDFMEMORY Buffer,
  [in] size_t NumBytesTransferred,
  [in] WDFCONTEXT Context
)
{...}

Parameter

[in] Pipe

Handel ke objek pipa kerangka kerja.

[in] Buffer

Handel ke objek memori kerangka kerja yang mewakili buffer yang berisi data dari perangkat.

[in] NumBytesTransferred

Jumlah byte data yang ada di buffer baca.

[in] Context

Informasi konteks yang ditentukan driver yang ditentukan driver dalam anggota EvtUsbTargetPipeReadCompleteContext dari struktur WDF_USB_CONTINUOUS_READER_CONFIG pipa.

Nilai kembali

Tidak ada

Keterangan

Untuk mendaftarkan fungsi panggilan balik EvtUsbTargetPipeReadComplete , driver harus menempatkan alamat fungsi dalam struktur WDF_USB_CONTINUOUS_READER_CONFIG .

Jika driver telah membuat pembaca berkelanjutan untuk pipa USB, kerangka kerja memanggil fungsi panggilan balik EvtUsbTargetPipeReadComplete driver setiap kali target I/O driver berhasil menyelesaikan permintaan baca. Fungsi panggilan balik dipanggil pada IRQL di mana target I/O menyelesaikan permintaan baca, yang biasanya IRQL = DISPATCH_LEVEL, tetapi tidak lebih tinggi dari DISPATCH_LEVEL. (Jika target I/O tidak berhasil menyelesaikan permintaan, kerangka kerja memanggil fungsi panggilan balik EvtUsbTargetPipeReadersFailed driver.)

Untuk mengakses buffer yang berisi data yang dibaca dari perangkat, driver dapat memanggil WdfMemoryGetBuffer. Kerangka kerja menulis data ke dalam buffer, setelah header yang ditentukan oleh anggota HeaderLength dari struktur WDF_USB_CONTINUOUS_READER_CONFIG . Perhatikan bahwa pointer yang dikembalikan WdfMemoryGetBuffer menunjuk ke awal header, tetapi parameter NumBytesTransferred fungsi callback EvtUsbTargetPipeReadCompletetidak menyertakan panjang header.

Secara default, kerangka kerja menghapus objek memori buffer setelah fungsi panggilan balik EvtUsbTargetPipeReadComplete kembali. Namun, Anda mungkin ingin objek memori tetap valid setelah fungsi panggilan balik kembali. Misalnya, Anda mungkin ingin driver menyimpan handel objek di ruang konteks objek pipa kerangka kerja sehingga driver dapat memproses konten objek memori setelah fungsi panggilan balik kembali. Untuk memperpanjang masa pakai objek memori, fungsi panggilan balik harus meneruskan handel objek memori ke WdfObjectReference. Selanjutnya, driver harus memanggil WdfObjectDereference sehingga kerangka kerja dapat menghapus objek.

Kerangka kerja menyinkronkan panggilan ke fungsi panggilan balik EvtUsbTargetPipeReadComplete dan EvtUsbTargetPipeReadersFailed sesuai dengan aturan berikut:

Fungsi panggilan balik ini tidak berjalan secara bersamaan untuk pipa USB individual.
Jika driver membuat beberapa pembaca berkelanjutan untuk beberapa pipa USB, dengan beberapa fungsi panggilan balik EvtUsbTargetPipeReadComplete dan EvtUsbTargetPipeReadersFailed , beberapa fungsi panggilan balik dapat berjalan secara bersamaan.
Jika driver telah menentukan nilai NumPendingReads default atau nilai yang lebih besar dari 1, dan jika permintaan baca selesai saat fungsi panggilan balik EvtUsbTargetPipeReadComplete dijalankan, kerangka kerja dapat memanggil fungsi panggilan balik EvtUsbTargetPipeReadComplete lagi sebelum fungsi panggilan balik kembali kembali.
Kerangka kerja tidak menyinkronkan fungsi panggilan balik ini dengan fungsi panggilan balik lainnya.

Dalam anggota BufferAttributes dari struktur WDF_USB_CONTINUOUS_READER_CONFIG , driver Anda dapat menentukan fungsi panggilan balik EvtCleanupCallback dan EvtDestroyCallback untuk objek memori. Jika Anda menentukan fungsi panggilan balik EvtCleanupCallback , kerangka kerja akan memanggil fungsi panggilan balik tersebut saat mencoba menghapus objek memori, setelah fungsi panggilan balik EvtUsbTargetPipeReadComplete kembali. Jika fungsi panggilan balik EvtUsbTargetPipeReadComplete telah disebut WdfObjectReference, fungsi panggilan balik EvtCleanupCallback (jika disediakan) tidak boleh memanggil WdfObjectDereference.

Driver harus memanggil WdfObjectDereference ketika telah selesai menggunakan objek memori. Kerangka kerja kemudian dapat memanggil fungsi panggilan balik EvtDestroyCallback driver (jika disediakan) dan menghapus objek memori.

Untuk informasi selengkapnya tentang fungsi panggilan balik EvtUsbTargetPipeReadComplete dan target I/O USB, lihat Target I/O USB.

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Versi UMDF minimum	2.0
Header	wdfusb.h (termasuk Wdf.h)
IRQL	<=DISPATCH_LEVEL (Lihat bagian Keterangan.)

Lihat juga

EvtUsbTargetPipeReadersFailed

WDF_USB_CONTINUOUS_READER_CONFIG

WdfMemoryGetBuffer

Bagikan melalui