EVT_WDF_USB_READER_COMPLETION_ROUTINE funzione di callback (wdfusb.h)

  • Articolo

[Si applica a KMDF e UMDF]

La funzione di callback dell'evento EvtUsbTargetPipeReadComplete di un driver informa il driver che un lettore continuo ha completato correttamente una richiesta di lettura.

Sintassi

EVT_WDF_USB_READER_COMPLETION_ROUTINE EvtWdfUsbReaderCompletionRoutine;

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

Parametri

[in] Pipe

Handle per un oggetto pipe del framework.

[in] Buffer

Handle per un oggetto memoria del framework che rappresenta un buffer che contiene dati dal dispositivo.

[in] NumBytesTransferred

Numero di byte di dati presenti nel buffer di lettura.

[in] Context

Informazioni sul contesto definite dal driver specificate nel membro EvtUsbTargetPipeReadCompleteContext della struttura WDF_USB_CONTINUOUS_READER_CONFIG della pipe.

Valore restituito

nessuno

Osservazioni

Per registrare una funzione di callback EvtUsbTargetPipeReadComplete , il driver deve inserire l'indirizzo della funzione in una struttura WDF_USB_CONTINUOUS_READER_CONFIG .

Se un driver ha creato un lettore continuo per una pipe USB, il framework chiama la funzione di callback EvtUsbTargetPipeReadComplete del driver ogni volta che la destinazione di I/O del driver completa correttamente una richiesta di lettura. La funzione di callback viene chiamata in IRQL in corrispondenza della quale la destinazione di I/O ha completato la richiesta di lettura, che in genere è IRQL = DISPATCH_LEVEL, ma non superiore a DISPATCH_LEVEL. Se la destinazione di I/O non completa correttamente una richiesta, il framework chiama la funzione di callback EvtUsbTargetPipeReadersFailed del driver.

Per accedere al buffer contenente i dati letti dal dispositivo, il driver può chiamare WdfMemoryGetBuffer. Il framework scrive i dati nel buffer, dopo l'intestazione definita dal membro HeaderLength della struttura WDF_USB_CONTINUOUS_READER_CONFIG . Si noti che il puntatore restituito da WdfMemoryGetBuffer punta all'inizio dell'intestazione, ma il parametro NumBytesTransferred della funzione di callback EvtUsbTargetPipeReadCompletenon include la lunghezza dell'intestazione.

Per impostazione predefinita, il framework elimina l'oggetto memoria del buffer dopo la restituzione della funzione di callback EvtUsbTargetPipeReadComplete . Tuttavia, potrebbe essere necessario che l'oggetto memory rimanga valido dopo la restituzione della funzione di callback. Ad esempio, è possibile che il driver archivii l'handle dell'oggetto nello spazio di contesto dell'oggetto pipe del framework in modo che il driver possa elaborare il contenuto dell'oggetto memoria dopo che la funzione di callback viene restituita. Per estendere la durata dell'oggetto memoria, la funzione di callback deve passare l'handle dell'oggetto memoria a WdfObjectReference. Successivamente, il driver deve chiamare WdfObjectDereference in modo che il framework possa eliminare l'oggetto.

Il framework sincronizza le chiamate alle funzioni di callback EvtUsbTargetPipeReadComplete e EvtUsbTargetPipeReadersFailed in base alle regole seguenti:

  • Queste funzioni di callback non vengono eseguite contemporaneamente per una singola pipe USB.
  • Se il driver crea più lettori continui per più pipe USB, con più funzioni di callback EvtUsbTargetPipeReadComplete e EvtUsbTargetPipeReadersFailed , le più funzioni di callback possono essere eseguite contemporaneamente.
  • Se il driver ha specificato il valore predefinito NumPendingReads o un valore maggiore di 1 e se una richiesta di lettura viene completata mentre la funzione di callback EvtUsbTargetPipeReadComplete è in esecuzione, il framework può chiamare nuovamente la funzione di callback EvtUsbTargetPipeReadComplete prima che la funzione di callback venga restituita.
  • Il framework non sincronizza queste funzioni di callback con altre funzioni di callback.
Nel membro BufferAttributes della struttura WDF_USB_CONTINUOUS_READER_CONFIG il driver può specificare le funzioni di callback EvtCleanupCallback e EvtDestroyCallback per l'oggetto memory. Se si specifica una funzione di callback EvtCleanupCallback , il framework chiamerà tale funzione di callback quando tenta di eliminare l'oggetto memoria, dopo che la funzione di callback EvtUsUsbTargetPipeReadComplete restituisce il risultato. Se la funzione di callback EvtUsbTargetPipeReadComplete ha chiamato WdfObjectReference, la funzione di callback EvtCleanupCallback (se specificato) non deve chiamare WdfObjectDereference.

Al termine dell'utilizzo dell'oggetto memory, il driver deve chiamare WdfObjectDereference . Il framework può quindi chiamare la funzione di callback EvtDestroyCallback del driver (se specificato) ed eliminare l'oggetto memoria.

Per altre informazioni sulla funzione di callback EvtUsbTargetPipeReadComplete e sulle destinazioni di I/O USB, vedere Destinazioni di I/O USB.

Requisiti

Requisito Valore
Piattaforma di destinazione Universale
Versione KMDF minima 1.0
Versione UMDF minima 2,0
Intestazione wdfusb.h (include Wdf.h)
IRQL <=DISPATCH_LEVEL (vedere la sezione Osservazioni).

Vedi anche

EvtUsbTargetPipeReadersFailed

WDF_USB_CONTINUOUS_READER_CONFIG

WdfMemoryGetBuffer