IWDFUsbTargetPipe2::ConfigureContinuousReader method (wudfusb.h)

Artikel
03/08/2023

[Peringatan: UMDF 2 adalah versi terbaru UMDF dan pengganti UMDF 1. Semua driver UMDF baru harus ditulis menggunakan UMDF 2. Tidak ada fitur baru yang ditambahkan ke UMDF 1 dan ada dukungan terbatas untuk UMDF 1 pada versi Windows 10 yang lebih baru. Driver Universal Windows harus menggunakan UMDF 2. Untuk informasi selengkapnya, lihat Mulai menggunakan UMDF.]

Metode ConfigureContinuousReader mengonfigurasi kerangka kerja untuk terus membaca dari pipa USB.

Sintaks

HRESULT ConfigureContinuousReader(
  [in]           SIZE_T                                              TransferLength,
  [in]           SIZE_T                                              HeaderLength,
  [in]           SIZE_T                                              TrailerLength,
  [in]           UCHAR                                               NumPendingReads,
  [in, optional] IUnknown                                            *pMemoryCleanupCallbackInterface,
  [in]           IUsbTargetPipeContinuousReaderCallbackReadComplete  *pOnCompletion,
  [in, optional] PVOID                                               pCompletionContext,
  [in, optional] IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailure
);

Parameter

[in] TransferLength

Panjang maksimum, dalam byte, data yang dapat diterima dari perangkat.

[in] HeaderLength

Offset, dalam byte, ke dalam buffer yang menerima data dari perangkat. Kerangka kerja akan menyimpan data dari perangkat dalam buffer baca, dimulai dari nilai offset. Dengan kata lain, ruang ini mendahului ruang berukuran TransferLength tempat kerangka kerja menyimpan data dari perangkat.

[in] TrailerLength

Panjangnya, dalam byte, dari ruang buffer berikutnya. Ruang ini mengikuti ruang berukuran TransferLength tempat kerangka kerja menyimpan data dari perangkat.

[in] NumPendingReads

Jumlah permintaan baca yang akan diantrekan kerangka kerja untuk menerima data dari target I/O. Jika nilai ini nol, kerangka kerja menggunakan jumlah permintaan baca default. Jika nilai yang ditentukan lebih besar dari nilai maksimum yang diizinkan, kerangka kerja menggunakan nilai maksimum yang diizinkan. Untuk informasi selengkapnya tentang parameter NumPendingReads , lihat bagian Keterangan berikut.

[in, optional] pMemoryCleanupCallbackInterface

Penunjuk ke antarmuka IUnkown yang disediakan driver yang digunakan kerangka kerja untuk mengakses fungsi panggilan balik IObjectCleanup::OnCleanup opsional. Kerangka kerja memanggil fungsi panggilan balik ketika membatalkan alokasi buffer baca yang dibuatnya untuk menangani operasi baca berkelanjutan. Parameter ini bersifat opsional dan dapat berupa NULL.

[in] pOnCompletion

Pointer ke antarmuka IUsbTargetPipeContinuousReaderCallbackReadComplete yang disediakan driver yang menyediakan fungsi panggilan balik OnReaderCompletion .

[in, optional] pCompletionContext

Penunjuk yang tidak ditik ke informasi konteks yang ditentukan driver yang diteruskan kerangka kerja ke fungsi panggilan balik IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion driver.

[in, optional] pOnFailure

Pointer ke antarmuka IUsbTargetPipeContinuousReaderCallbackReadersFailed yang disediakan driver yang menyediakan fungsi panggilan balik OnReaderFailure .

Nilai kembali

ConfigureContinuousReader mengembalikan S_OK jika operasi berhasil. Jika tidak, metode ini dapat mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
HRESULT_FROM_NT (STATUS_INVALID_DEVICE_STATE)	Driver telah mengonfigurasi pembaca berkelanjutan untuk pipa USB. Pipa USB tidak disiapkan untuk transfer input massal atau mengganggu.
E_OUTOFMEMORY	Upaya kerangka kerja untuk mengalokasikan buffer gagal.
ERROR_ARITHMETIC_OVERFLOW	Parameter TransferLength, HeaderLength, atau TrailerLength menentukan ukuran yang terlalu besar atau tidak valid.

Metode ini mungkin mengembalikan salah satu nilai lain yang dikandung Winerror.h.

Keterangan

Anda dapat mengonfigurasi pembaca berkelanjutan untuk pipa massal atau pipa interupsi. Pipa harus memiliki titik akhir input.

Setelah memanggil ConfigureContinuousReader untuk mengonfigurasi pembaca berkelanjutan, driver Anda harus memanggil IWDFIoTargetStateManagement::Start untuk memulai pembaca. Untuk menghentikan pembaca, driver harus memanggil IWDFIoTargetStateManagement::Stop.

Biasanya, driver memanggil ConfigureContinuousReader dari dalam fungsi panggilan balik IPnpCallbackHardware::OnPrepareHardware . Driver harus memanggil fungsi panggilan balik IWDFIoTargetStateManagement::Start dari dalam fungsi panggilan balik IPnpCallback::OnD0Entry dan harus memanggil IWDFIoTargetStateManagement::Stop dari dalam fungsi panggilan balik IPnpCallback::OnD0Exit .

Setiap kali target I/O pipa berhasil menyelesaikan permintaan baca, kerangka kerja memanggil fungsi panggilan balik IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion driver. Jika target I/O melaporkan kegagalan saat memproses permintaan, kerangka kerja memanggil fungsi panggilan balik IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure driver setelah semua permintaan baca selesai. (Oleh karena itu, fungsi panggilan balik OnReaderCompletion tidak akan dipanggil saat fungsi panggilan balik OnReaderFailure sedang dijalankan.)

Gunakan panduan berikut untuk memilih nilai untuk parameter NumPendingReads :

Atur NumPendingReads ke nol jika Anda ingin driver Anda menggunakan nilai default kerangka kerja.
Nilai default lebih besar dari satu dan memberikan performa yang cukup baik untuk banyak perangkat pada banyak konfigurasi prosesor.
Atur NumPendingReads ke satu jika penting bahwa driver Anda menerima buffer data dalam urutan yang tepat di mana perangkat mengirimkan data.
Jika kerangka kerja mengantre lebih dari satu permintaan baca, driver mungkin tidak menerima buffer data dalam urutan yang sama di mana perangkat mengirimkan data.
Atur NumPendingReads ke angka yang memenuhi persyaratan performa untuk perangkat Anda, berdasarkan pengukuran performa menyeluruh.
Pertama, uji perangkat Anda dengan nilai default (0) untuk NumPendingReads. Pengujian Anda harus mencakup berbagai konfigurasi perangkat keras, termasuk berbagai jenis dan jumlah prosesor, dan pengontrol host USB dan konfigurasi USB yang berbeda. Anda kemudian dapat bereksperimen dengan nilai yang lebih tinggi, menggunakan pengujian yang sama. Driver yang mungkin memerlukan nilai lebih tinggi adalah salah satu untuk perangkat yang memiliki tingkat interupsi tinggi, di mana data dapat hilang jika gangguan tidak dilayanakan dengan cepat.

Nilai NumPendingReads yang terlalu besar dapat memperlambat performa sistem. Anda harus menggunakan nilai terendah yang memenuhi persyaratan performa Anda. Biasanya, nilai yang lebih tinggi dari tiga atau empat tidak meningkatkan throughput data. Tetapi nilai yang lebih tinggi dapat mengurangi latensi, atau kemungkinan data hilang, pada pipa frekuensi tinggi.

Setelah driver memanggil ConfigureContinuousReader, driver tidak dapat menggunakan IWDFIoRequest::Send untuk mengirim permintaan I/O ke pipa kecuali fungsi callback IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure dipanggil dan mengembalikan FALSE.

Untuk informasi selengkapnya tentang metode ConfigureContinuousReader dan target I/O USB, lihat Membaca dari Pipa UMDF-USB.

Contoh

Contoh kode berikut mengonfigurasi pembaca berkelanjutan. Dalam contoh ini, ukuran buffer maksimum adalah ukuran buffer yang ditentukan driver. Offset buffer header dan trailer diatur ke nol, dan jumlah operasi baca yang tertunda diatur ke dua. Contoh menggunakan penunjuk antarmuka pipa target untuk parameter pCompletionContext , sehingga fungsi panggilan balik OnReaderCompletion dapat menentukan pipa tempat operasi baca selesai.

HRESULT hr, hrQI;
IUsbTargetPipeContinuousReaderCallbackReadComplete *pOnCompletionCallback = NULL;
IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailureCallback= NULL;
IWDFUsbTargetPipe2 * pIUsbInterruptPipe2;

//
// Obtain interfaces.
//
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnCompletionCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnFailureCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = m_pIUsbInterruptPipe->QueryInterface(IID_PPV_ARGS(&pIUsbInterruptPipe2));
if (!SUCCEEDED(hrQI)) goto Error;

//
// Configure the reader.
//
hr = pIUsbInterruptPipe2->ConfigureContinuousReader(
                                                    sizeof(m_MyBuffer), 
                                                    0,
                                                    0,
                                                    2, 
                                                    NULL,
                                                    pOnCompletionCallback,
                                                    m_pIUsbTargetPipe,
                                                    pOnFailureCallback
                                                    );
...

Persyaratan

Persyaratan	Nilai
Akhir dukungan	Tidak tersedia di UMDF 2.0 dan yang lebih baru.
Target Platform	Desktop
Versi UMDF minimum	1.9
Header	wudfusb.h (termasuk Wudfusb.h)
DLL	WUDFx.dll