Funzione WdfUsbTargetPipeConfigContinuousReader (wdfusb.h)

Articolo
02/29/2024

[Si applica a KMDF e UMDF]

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

Sintassi

NTSTATUS WdfUsbTargetPipeConfigContinuousReader(
  [in] WDFUSBPIPE                        Pipe,
  [in] PWDF_USB_CONTINUOUS_READER_CONFIG Config
);

Parametri

[in] Pipe

Handle per un oggetto pipe del framework ottenuto chiamando WdfUsbInterfaceGetConfiguredPipe.

[in] Config

Puntatore a una struttura WDF_USB_CONTINUOUS_READER_CONFIG allocata dal chiamante.

Valore restituito

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

Codice restituito	Descrizione
STATUS_INFO_LENGTH_MISMATCH	La dimensione della struttura WDF_USB_CONTINUOUS_READER_CONFIG specificata dal parametro Config non è corretta.
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente disponibile.
STATUS_INVALID_DEVICE_REQUEST	Il tipo della pipe non è valido.
STATUS_INTEGER_OVERFLOW	Membro HeaderLength, TransferLength o TrailerLength della struttura WDF_USB_CONTINUOUS_READER_CONFIG che il parametro Config ha specificato una dimensione troppo grande o altrimenti non valida.
STATUS_INVALID_BUFFER_SIZE	Le dimensioni del buffer di lettura non erano un multiplo delle dimensioni massime del pacchetto della pipe.

Per un elenco di altri valori restituiti che il metodo WdfUsbTargetPipeConfigContinuousReader potrebbe restituire, vedere Errori di creazione di oggetti framework.

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

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 WdfUsbTargetPipeConfigContinuousReader per configurare un lettore continuo, il driver deve chiamare WdfIoTargetStart per avviare il lettore. Per arrestare il lettore, il driver deve chiamare WdfIoTargetStop.

In genere, un driver chiama WdfUsbTargetPipeConfigContinuousReader dall'interno della relativa funzione di callback EvtDevicePrepareHardware . Il driver deve chiamare WdfIoTargetStart dall'interno della funzione di callback EvtDeviceD0Entry e deve chiamare WdfIoTargetStop dall'interno della relativa funzione di callback EvtDeviceD0Exit .

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

Se non si specifica il callback EvtUsbTargetPipeReadersFailed facoltativo, il framework risponde a un tentativo di lettura non riuscito inviando un'altra richiesta di lettura. Pertanto, se il bus è in uno stato in cui non accetta letture, il framework invia continuamente nuove richieste per il ripristino da una lettura non riuscita.

Dopo che un driver ha chiamato WdfUsbTargetPipeConfigContinuousReader, il driver non può usare WdfUsbTargetPipeReadSynchronously o WdfRequestSend per inviare richieste di I/O alla pipe a meno che il lettore continuo non sia stato arrestato. Per arrestare il lettore, il driver può chiamare WdfIoTargetStop o restituire FALSE dalla relativa funzione di callback EvtUsbTargetPipeReadersFailed . Se il driver chiama WdfUsbTargetPipeReadSynchronously mentre il lettore viene arrestato, deve impostare il flag WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE nel membro Flags del parametro RequestOptions . In caso contrario, la richiesta verrà sospesa fino al riavvio della destinazione.

Il framework imposta il flag di USBD_SHORT_TRANSFER_OK nel relativo RIQUADRO interno. L'impostazione di questo flag consente all'ultimo pacchetto di un trasferimento dati di essere inferiore alla dimensione massima del pacchetto.

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

Esempio

L'esempio di codice seguente inizializza una struttura WDF_USB_CONTINUOUS_READER_CONFIG e chiama WdfUsbTargetPipeConfigContinuousReader.

WDF_USB_CONTINUOUS_READER_CONFIG  contReaderConfig;
NTSTATUS  status;

WDF_USB_CONTINUOUS_READER_CONFIG_INIT(
                                      &contReaderConfig,
                                      OsrFxEvtUsbInterruptPipeReadComplete,
                                      DeviceContext,
                                      sizeof(UCHAR)
                                      );
status = WdfUsbTargetPipeConfigContinuousReader(
                                      Pipe,
                                      &contReaderConfig
                                      );

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdfusb.h (include Wdfusb.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), FailD0EntryIoTargetState(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbContReader(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)