Metodo IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion (wudfusb.h)

Articolo
03/05/2024

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Nessuna nuova funzionalità viene aggiunta 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, vedere Introduzione con UMDF.]

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

Sintassi

void OnReaderCompletion(
  [in] IWDFUsbTargetPipe *pPipe,
  [in] IWDFMemory        *pMemory,
  [in] SIZE_T            NumBytesTransferred,
  [in] PVOID             Context
);

Parametri

[in] pPipe

Puntatore all'interfaccia IWDFUsbTargetPipe per la pipe USB in cui il driver ha abilitato un lettore continuo.

[in] pMemory

Puntatore all'interfaccia IWDFMemory per un buffer di lettura che contiene dati letti dalla pipe USB.

[in] NumBytesTransferred

Numero di byte che il buffer di lettura contiene.

[in] Context

Puntatore a informazioni di contesto fornite dal driver fornite dal driver quando in precedenza denominato IWDFUsbTargetPipe2::ConfigureContinuousReader.

Valore restituito

nessuno

Osservazioni

Per registrare una funzione di callback IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion , il driver deve fornire un puntatore all'interfaccia IUsbTargetPipeContinuousReaderCallbackReadComplete quando chiama IWDFUsbTargetPipe2::ConfigureContinuousReader.

Se un driver ha creato un lettore continuo per una pipe USB, il framework chiama la funzione di callback OnReaderCompletion del driver ogni volta che la destinazione I/O del driver completa correttamente una richiesta di lettura. Se la destinazione di I/O non completa correttamente una richiesta, il framework chiama la funzione di callback IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure callback.

Per accedere al buffer contenente i dati letti dal dispositivo, il driver può chiamare IWDFMemory::GetDataBuffer. Il framework scrive i dati nel buffer, dopo l'intestazione definita dal parametro HeaderLength di IWDFUsbTargetPipe2::ConfigureContinuousReader. Si noti che il puntatore che IWDFMemory::GetDataBuffer restituisce punti all'inizio dell'intestazione, ma il parametro NumBytesTransferred della funzione di callback onReaderCompletion non include la lunghezza dell'intestazione.

Per impostazione predefinita, il framework elimina l'oggetto memoria del buffer dopo che la funzione di callback OnReaderCompletion restituisce. Tuttavia, è possibile che l'oggetto memoria rimanga valido dopo che la funzione di callback restituisce. Ad esempio, è possibile che il driver archivii il puntatore dell'interfaccia dell'oggetto memoria 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 restituisce. Per estendere la durata dell'oggetto memoria, la funzione callback deve chiamare il metodo IWDFMemory::AddRef del buffer. Successivamente, il driver deve chiamare il metodo IWDFMemory::Release del buffer in modo che il framework possa eliminare l'oggetto.

Il framework sincronizza le chiamate alle funzioni di callback OnReaderCompletion e IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure callback 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 OnReaderCompletion e OnReaderFailure , le funzioni di callback multiple possono essere eseguite simultaneamente.
Se il driver ha specificato il valore NumPendingReads predefinito quando chiama IWDFUsbTargetPipe2::ConfigureContinuousReader (o se specifica un valore NumPendingReads maggiore di 1) e se una richiesta di lettura viene completata mentre la funzione callback OnReaderCompletion viene eseguita, il framework può chiamare nuovamente la funzione di callback OnReaderCompletion prima che la funzione callback restituisca.
Il framework non sincronizza queste funzioni di callback con altre funzioni di callback.

Quando il driver chiama IWDFUsbTargetPipe2::ConfigureContinuousReader, può specificare una funzione di callback IObjectCleanup::OnCleanup . Il framework chiamerà la funzione di callback quando tenta di eliminare l'oggetto memory, dopo che la funzione di callback OnReaderCompletion restituisce.

Per altre informazioni sulla funzione di callback OnReaderCompletion e sulle destinazioni di I/O USB, vedere Gestione di una destinazione di I/O USB.

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)

Vedi anche

IUsbTargetPipeContinuousReaderCallbackReadComplete

IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure

Condividi tramite