Funzione WdfUsbTargetPipeReadSynchronously (wdfusb.h)
[Si applica a KMDF e UMDF]
Il metodo WdfUsbTargetPipeReadSynchronously compila una richiesta di lettura e lo invia in modo sincrono a una pipe di input USB specificata.
Sintassi
NTSTATUS WdfUsbTargetPipeReadSynchronously(
[in] WDFUSBPIPE Pipe,
[in, optional] WDFREQUEST Request,
[in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[in, optional] PWDF_MEMORY_DESCRIPTOR MemoryDescriptor,
[out, optional] PULONG BytesRead
);
Parametri
[in] Pipe
Handle per un oggetto pipe del framework ottenuto chiamando WdfUsbInterfaceGetConfiguredPipe.
[in, optional] Request
Handle per un oggetto richiesta del framework. Questo parametro è facoltativo e può essere NULL. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
[in, optional] RequestOptions
Puntatore a una struttura WDF_REQUEST_SEND_OPTIONS allocata dal chiamante che specifica le opzioni per la richiesta. Questo puntatore è facoltativo e può essere NULL. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
[in, optional] MemoryDescriptor
Puntatore a una struttura WDF_MEMORY_DESCRIPTOR allocata dal chiamante che descrive il buffer che riceverà i dati dal dispositivo. Le dimensioni del buffer devono essere multiple delle dimensioni massime del pacchetto della pipe, a meno che il driver non abbia chiamato WdfUsbTargetPipeSetNoMaximumPacketSizeCheck. Per altre informazioni su questo buffer, vedere la sezione Osservazioni seguente.
[out, optional] BytesRead
Puntatore a una posizione che riceve il numero di byte letti, se l'operazione ha esito positivo. Questo parametro è facoltativo e può essere NULL.
Valore restituito
WdfUsbTargetPipeReadSynchronously restituisce il valore di stato di completamento della destinazione I/O se l'operazione ha esito positivo. In caso contrario, questo metodo può restituire uno dei valori seguenti:
| Codice restituito | Descrizione |
|---|---|
|
La dimensione della struttura WDF_REQUEST_SEND_OPTIONS a cui puntaVa RequestOptions non è corretta. |
|
È stato rilevato un parametro non valido. |
|
Memoria insufficiente disponibile. |
|
IrQL del chiamante non è stato PASSIVE_LEVEL, è stato specificato un descrittore di memoria non valido, il tipo della pipe non è valido, la direzione di trasferimento non è valida o la richiesta di I/O specificata è già stata accodata a una destinazione di I/O. |
|
Le dimensioni del buffer non erano un multiplo delle dimensioni massime del pacchetto della pipe. |
|
Il driver ha fornito un valore di timeout e la richiesta non è stata completata entro il tempo assegnato. |
|
Il pacchetto di richiesta di I/O rappresentato dal parametro Request non fornisce strutture IO_STACK_LOCATION sufficienti per consentire al driver di inoltrare la richiesta. |
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
Usare il metodo WdfUsbTargetPipeReadSynchronously per inviare le richieste di lettura in modo sincrono. Per inviare richieste di lettura in modo asincrono, usare WdfUsbTargetPipeFormatRequestForRead, seguito da WdfRequestSend.
La pipe specificata dal parametro Pipe deve essere una pipe di input e il tipo della pipe deve essere WdfUsbPipeTypeBulk o WdfUsbPipeTypeInterrupt.
Il metodo WdfUsbTargetPipeReadSynchronously non restituisce fino al completamento della richiesta, a meno che il driver non fornisca un valore di timeout nella struttura WDF_REQUEST_SEND_OPTIONS a cui punta il parametro RequestOptions o a meno che non venga rilevato un errore.
È possibile inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O oppure creare e inviare una nuova richiesta. In entrambi i casi, il framework richiede un oggetto richiesta e uno spazio buffer.
Per inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O:
- Specificare l'handle della richiesta ricevuta per il parametro Request .
-
Usare il buffer di output della richiesta ricevuta per il parametro MemoryDescriptor del metodo WdfUsbTargetPipeReadSynchronously.
Il driver deve chiamare WdfRequestRetrieveOutputMemory per ottenere un handle a un oggetto memoria framework che rappresenta il buffer di output della richiesta e quindi posizionare tale handle nella struttura WDF_MEMORY_DESCRIPTOR a cui punta MemoryDescriptor .
I driver spesso dividono le richieste di I/O ricevute in richieste più piccole inviate a una destinazione di I/O, in modo che il driver possa creare nuove richieste.
Per creare una nuova richiesta di I/O:
-
Specificare un handle di richiesta NULL nel parametro Request del metodo WdfUsbTargetPipeReadSynchronously oppure creare un nuovo oggetto richiesta e fornire il relativo handle:
- Se si specifica un handle di richiesta NULL , il framework usa un oggetto richiesta interno. Questa tecnica è semplice da usare, ma il driver non può annullare la richiesta.
- Se chiami WdfRequestCreate per creare uno o più oggetti richiesta, puoi riutilizzare questi oggetti richiesta chiamando WdfRequestReuse. Questa tecnica consente alla funzione di callback EvtDriverDeviceAdd del driver di preallocare gli oggetti richiesta per un dispositivo. Inoltre, un altro thread del driver può chiamare WdfRequestCancelSentRequest per annullare la richiesta, se necessario.
Il driver può specificare un parametro RequestOptions diverso da NULL, indipendentemente dal fatto che il driver fornisca un parametro non NULL o nullRequest. È ad esempio possibile usare il parametro RequestOptions per specificare un valore di timeout.
-
Fornire spazio buffer per il parametro MemoryDescriptor del metodo WdfUsbTargetPipeReadSynchronously.
Il driver può specificare questo spazio buffer come buffer allocato in locale, come handle WDFMEMORY o come MDL. È possibile usare qualsiasi metodo sia più pratico.
Se necessario, il framework converte la descrizione del buffer in quella corretta per il metodo della destinazione di I/O per l'accesso ai buffer di dati.
Sono disponibili le tecniche seguenti:
-
Specificare un buffer locale
Poiché WdfUsbTargetPipeReadSynchronously gestisce le richieste di I/O in modo sincrono, il driver può creare buffer di richiesta locali per la routine chiamante, come illustrato nell'esempio di codice seguente.
WDF_MEMORY_DESCRIPTOR memoryDescriptor; MY_BUFFER_TYPE myBuffer; WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor, (PVOID) &myBuffer, sizeof(myBuffer)); -
Fornire un handle WDFMEMORY
Chiamare WdfMemoryCreate o WdfMemoryCreatePreallocated per ottenere un handle per la memoria gestita dal framework, come illustrato nell'esempio di codice seguente.
WDF_MEMORY_DESCRIPTOR memoryDescriptor; WDFMEMORY memoryHandle = NULL; status = WdfMemoryCreate(NULL, NonPagedPool, POOL_TAG, MY_BUFFER_SIZE, &memoryHandle, NULL); WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&memoryDescriptor, memoryHandle, NULL);In alternativa, il driver può chiamare WdfRequestRetrieveOutputMemory per ottenere un handle a un oggetto memoria del framework che rappresenta il buffer di output di una richiesta di I/O ricevuta, se si vuole che il driver passi il contenuto del buffer alla destinazione di I/O. Il driver non deve completare la richiesta di I/O ricevuta finché la nuova richiesta inviata da WdfUsbTargetPipeReadSynchronously alla destinazione di I/O è stata eliminata, riutilizzata o riformattata. WdfUsbTargetPipeReadSynchronously incrementa il conteggio dei riferimenti dell'oggetto memoria. L'eliminazione, il riutilizzo o la riformattazione di un oggetto richiesta decrementa il conteggio dei riferimenti dell'oggetto memoria.
-
Specificare un MDL
I driver possono ottenere il file MDL associato a una richiesta di I/O ricevuta chiamando WdfRequestRetrieveOutputWdmMdl.
-
Specificare un buffer locale
Un driver non può chiamare WdfUsbTargetPipeReadSynchronously se ha configurato un lettore continuo per la pipe.
Per informazioni su come ottenere informazioni sullo stato dopo il completamento di una richiesta di I/O, vedere Ottenere informazioni di completamento.
Per altre informazioni sul metodo WdfUsbTargetPipeReadSynchronously e sulle destinazioni di I/O USB, vedere Destinazioni di I/O USB.
Esempio
L'esempio di codice seguente crea un oggetto memoria framework, inizializza una struttura WDF_MEMORY_DESCRIPTOR e passa la struttura a WdfUsbTargetPipeReadSynchronously. In questo esempio viene specificato NULL per l'handle dell'oggetto richiesta, pertanto il framework creerà un nuovo oggetto richiesta per la destinazione di I/O.
WDFMEMORY wdfMemory;
WDF_MEMORY_DESCRIPTOR readBufDesc;
ULONG BytesRead;
status = WdfMemoryCreate(
WDF_NO_OBJECT_ATTRIBUTES,
NonPagedPool,
0,
readSize,
&wdfMemory,
NULL
);
if (!NT_SUCCESS(status)){
return ;
}
buffer = WdfMemoryGetBuffer(
wdfMemory,
NULL
);
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
&readBufDesc,
buffer,
readSize
);
status = WdfUsbTargetPipeReadSynchronously(
Pipe,
NULL,
NULL,
&readBufDesc,
&BytesRead
);
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 | PASSIVE_LEVEL |
| Regole di conformità DDI | DriverCreate(kmdf), InternalIoctlReqs(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf), WriteReqs(kmdf) |
Vedi anche
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per