Metodo IWDFUsbTargetPipe2::ConfigureContinuousReader (wudfusb.h)

Articolo
02/07/2025

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Non vengono aggiunte nuove funzionalità a UMDF 1 ed è disponibile un supporto limitato per UMDF 1 nelle versioni più recenti di Windows 10. I driver di Windows universali devono usare UMDF 2. Per altre informazioni, vedi Introduzione a UMDF.]

Il metodo ConfigureContinuousReader configura il framework per la lettura continua da una pipe USB.

Sintassi

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
);

Parametri

[in] TransferLength

Lunghezza massima, in byte, dei dati che possono essere ricevuti dal dispositivo.

[in] HeaderLength

Offset, in byte, nel buffer che riceve i dati dal dispositivo. Il framework archivierà i dati dal dispositivo in un buffer di lettura, a partire dal valore di offset. In altre parole, questo spazio precede il TransferLengthspazio ridimensionato in cui il framework archivia i dati dal dispositivo.

[in] TrailerLength

Lunghezza, in byte, di uno spazio del buffer finale. Questo spazio segue lo spazio TransferLengthin cui il framework archivia i dati dal dispositivo.

[in] NumPendingReads

Numero di richieste di lettura che il framework accoderà per ricevere dati dalla destinazione di I/O. Se questo valore è zero, il framework usa un numero predefinito di richieste di lettura. Se il valore specificato è maggiore del valore massimo consentito, il framework usa il valore massimo consentito. Per altre informazioni sul parametro NumPendingReads, vedere la sezione Osservazioni seguente.

[in, optional] pMemoryCleanupCallbackInterface

Puntatore a un'interfaccia IUnkown fornita dal driver usata dal framework per accedere a una funzione di callback facoltativa IObjectClean up::OnCleanup. Il framework chiama la funzione di callback quando dealloca il buffer di lettura creato per gestire l'operazione di lettura continua. Questo parametro è facoltativo e può essere NULL.

[in] pOnCompletion

Puntatore a un'interfaccia fornita dal driver IUsbTargetPipeContinuousReaderCallbackReadComplete che fornisce una funzione di callback OnReaderCompletion.

[in, optional] pCompletionContext

Puntatore non tipizzato alle informazioni sul contesto definite dal driver passate dal framework alla funzione di callback IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion.

[in, optional] pOnFailure

Puntatore a un'interfaccia fornita dal driver IUsbTargetPipeContinuousReaderCallbackReadersFailed che fornisce una funzione di callback OnReaderFailure.

Valore restituito

ConfigureContinuousReader restituisce S_OK se l'operazione ha esito positivo. In caso contrario, questo metodo può restituire uno dei valori seguenti:

Codice restituito	Descrizione
HRESULT_FROM_NT (STATUS_INVALID_DEVICE_STATE)	Il driver ha già configurato un lettore continuo per la pipe USB. La pipe USB non è configurata per i trasferimenti di input bulk o interrupt.
E_OUTOFMEMORY	Il tentativo del framework di allocare un buffer non è riuscito.
ERROR_ARITHMETIC_OVERFLOW	Il parametro TransferLength, HeaderLengtho TrailerLength ha specificato una dimensione troppo grande o altrimenti non valida.

Questo metodo potrebbe restituire uno degli altri valori contenuti in Winerror.h.

Osservazioni

È possibile configurare un lettore continuo per una pipe bulk o una pipe di interrupt. La pipe deve avere un endpoint di input.

Dopo aver chiamato ConfigureContinuousReader per configurare un lettore continuo, il driver deve chiamare IWDFIoTargetStateManagement::Start per avviare il lettore. Per arrestare il lettore, il driver deve chiamare IWDFIoTargetStateManagement::Stop.

In genere, un driver chiama ConfigureContinuousReader dall'interno del IPnpCallbackHardware::OnPrepareHardware funzione di callback. Il driver deve chiamare funzione di callback IWDFIoTargetStateManagement::Start dall'interno del IPnpCallback::OnD0Entry funzione di callback e deve chiamare funzione di callback IWDFIoTargetStateManagement::Stop dall'interno del IPnpCallback::OnD0Exit funzione di callback.

Ogni volta che la destinazione di I/O della pipe completa correttamente una richiesta di lettura, il framework chiama il IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion funzione di callback. Se la destinazione di I/O segnala un errore durante l'elaborazione di una richiesta, il framework chiama la funzione di callback del driver IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure funzione di callback dopo il completamento di tutte le richieste di lettura. Pertanto, la OnReaderCompletion funzione di callback non verrà chiamata mentre la funzione di callback OnReaderFailure è in esecuzione.

Usare le linee guida seguenti per scegliere un valore per il parametro NumPendingReads:

Impostare NumPendingReads su zero se si vuole che il driver usi il valore predefinito del framework.
Il valore predefinito è maggiore di uno e offre prestazioni ragionevolmente buone per molti dispositivi in molte configurazioni del processore.
Impostare NumPendingReads su uno se è importante che il driver riceva buffer di dati nell'ordine esatto in cui il dispositivo recapita i dati.
Se il framework accoda più di una richiesta di lettura, il driver potrebbe non ricevere i buffer di dati nello stesso ordine in cui il dispositivo recapita i dati.
Impostare NumPendingReads su un numero che soddisfi i requisiti di prestazioni per il dispositivo, in base alle misurazioni approfondite delle prestazioni.
Prima di tutto, testare il dispositivo con il valore predefinito (0) per NumPendingReads. I test devono includere varie configurazioni hardware, tra cui tipi e numeri diversi di processori, e diversi controller host USB e configurazioni USB. È quindi possibile sperimentare con valori più elevati, usando gli stessi test. Un driver che potrebbe richiedere un valore superiore è uno per un dispositivo con una frequenza di interruzione elevata, in cui i dati possono essere persi se gli interrupt non vengono gestiti rapidamente.

Un valore NumPendingReads troppo grande può rallentare le prestazioni di un sistema. È consigliabile usare il valore più basso che soddisfi i requisiti di prestazioni. In genere, i valori superiori a tre o quattro non migliorano la velocità effettiva dei dati. Ma valori più elevati potrebbero ridurre la latenza o la probabilità di dati mancanti su una pipe ad alta frequenza.

Dopo che un driver ha chiamato ConfigureContinuousReader, il driver non può usare IWDFIoRequest::Send per inviare richieste di I/O alla pipe, a meno che non venga chiamato il IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure funzione di callback viene chiamata e restituisce FALSE.

Per altre informazioni sul metodo di ConfigureContinuousReader e sulle destinazioni di I/O USB, vedere Lettura da un UMDF-USB pipe.

Esempi

Nell'esempio di codice seguente viene configurato un lettore continuo. In questo esempio le dimensioni massime del buffer sono le dimensioni di un buffer definito dal driver. Gli offset dell'intestazione e del buffer trailer sono impostati su zero e il numero di operazioni di lettura in sospeso è impostato su due. Nell'esempio viene usato il puntatore dell'interfaccia della pipe di destinazione per il parametro pCompletionContext, quindi la OnReaderCompletion funzione di callback può determinare la pipe su cui è stata completata l'operazione di lettura.

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
                                                    );
...

Fabbisogno

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
piattaforma di destinazione	Desktop
versione minima di UMDF	1.9
intestazione	wudfusb.h (include Wudfusb.h)
dll	WUDFx.dll