Metodo IWDFUsbTargetPipe2::ConfigureContinuousReader (wudfusb.h)

Articolo
03/08/2023

[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 info, vedi Introduzione con 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 lo spazio di dimensioni TransferLength 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 di dimensioni TransferLength in 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 IObjectCleanup::OnCleanup facoltativa. 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 IUsbTargetPipeContinuousReaderCallbackReadComplete fornita dal driver che fornisce una funzione di callback OnReaderCompletion .

[in, optional] pCompletionContext

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

[in, optional] pOnFailure

Puntatore a un'interfaccia IUsbTargetPipeContinuousReaderCallbackReadersFailed fornita dal driver 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, HeaderLength o TrailerLength ha specificato una dimensione troppo grande o altrimenti non valida.

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

Commenti

È 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 dalla relativa funzione di callback IPnpCallbackHardware::OnPrepareHardware . Il driver deve chiamare IWDFIoTargetStateManagement::Start dall'interno della funzione di callback IPnpCallback::OnD0Entry e deve chiamare IWDFIoTargetStateManagement::Stop dall'interno della relativa funzione di callback IPnpCallback::OnD0Exit .

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

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 ottimali 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 a 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 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 la funzione di callback IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure non venga chiamata e restituisce FALSE.

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

Esempio

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 di intestazione e buffer trailer sono impostati su zero e il numero di operazioni di lettura in sospeso è impostato su due. Nell'esempio viene utilizzato il puntatore di interfaccia della pipe di destinazione per il parametro pCompletionContext , quindi la funzione di callback OnReaderCompletion 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
                                                    );
...

Requisiti

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
Piattaforma di destinazione	Desktop
Versione UMDF minima	1,9
Intestazione	wudfusb.h (include Wudfusb.h)
DLL	WUDFx.dll