Funzione WdfUsbTargetPipeFormatRequestForRead (wdfusb.h)
[Si applica a KMDF e UMDF]
Il metodo WdfUsbTargetPipeFormatRequestForRead compila una richiesta di lettura per una pipe di input USB, ma non invia la richiesta.
Sintassi
NTSTATUS WdfUsbTargetPipeFormatRequestForRead(
[in] WDFUSBPIPE Pipe,
[in] WDFREQUEST Request,
[in, optional] WDFMEMORY ReadMemory,
[in, optional] PWDFMEMORY_OFFSET ReadOffset
);
Parametri
[in] Pipe
Handle a un oggetto pipe del framework ottenuto chiamando WdfUsbInterfaceGetConfiguredPipe.
[in] Request
Handle per un oggetto richiesta framework. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
[in, optional] ReadMemory
Handle per un oggetto memoria framework. Questo oggetto rappresenta un buffer che riceverà i dati dalla pipe. Le dimensioni del buffer devono essere più 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 seguenti.
[in, optional] ReadOffset
Puntatore a una struttura WDFMEMORY_OFFSET allocata dal chiamante che fornisce valori facoltativi di offset e lunghezza di byte. Il framework usa questi valori per determinare l'indirizzo iniziale e la lunghezza, all'interno del buffer di lettura, per il trasferimento dei dati. Se questo puntatore è NULL, il trasferimento dei dati inizia all'inizio del buffer e la dimensione del trasferimento è la dimensione del buffer.
Valore restituito
WdfUsbTargetPipeFormatRequestForRead restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo può restituire uno dei valori seguenti:
| Codice restituito | Descrizione |
|---|---|
|
È stato rilevato un parametro non valido. |
|
Memoria insufficiente disponibile. |
|
È 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. |
|
Offset specificato dal parametro Offset non valido. |
|
Le dimensioni del buffer non erano più delle dimensioni massime del pacchetto della pipe. Le dimensioni del buffer devono essere più delle dimensioni massime del pacchetto della pipe, a meno che il driver non abbia chiamato WdfUsbTargetPipeSetNoMaximumPacketSizeCheck. |
|
Il pacchetto di richiesta I/O (IRP) che il parametro Request rappresenta non fornisce strutture IO_STACK_LOCATION sufficienti per consentire al driver di inoltrare la richiesta. |
Questo metodo potrebbe restituire anche altri valori NTSTATUS.
Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.
Commenti
Usare WdfUsbTargetPipeFormatRequestForRead, seguito da WdfRequestSend, per inviare richieste di lettura in modo sincrono o asincrono. In alternativa, usare il metodo WdfUsbTargetPipeReadSynchronously per inviare richieste di lettura in modo sincrono.
La pipe specificata dal parametro Pipe deve essere una pipe di input e il tipo della pipe deve essere WdfUsbPipeTypeBulk o WdfUsbPipeTypeInterrupt.
È possibile inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O oppure è possibile creare e inviare una nuova richiesta. In entrambi i casi, il framework richiede un oggetto request 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 del metodo WdfUsbTargetPipeFormatRequestForRead.
-
Usare il buffer di output della richiesta ricevuta per il parametro ReadMemory del metodo WdfUsbTargetPipeFormatRequestForRead.
Il driver deve chiamare WdfRequestRetrieveOutputMemory per ottenere un handle a un oggetto memoria del framework che rappresenta il buffer di output della richiesta e usare tale handle come valore per il parametro ReadMemory .
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:
-
Creare un nuovo oggetto request e specificare il relativo handle per il parametro Request del metodo WdfUsbTargetPipeFormatRequestForRead.
Chiamare WdfRequestCrea per preallocare uno o più oggetti richiesta. È possibile riutilizzare questi oggetti richiesta chiamando WdfRequestReuse. La funzione di callback EvtDriverDevice del driver può preallocare gli oggetti di richiesta per un dispositivo.
-
Fornire spazio del buffer e fornire l'handle del buffer per il parametro ReadMemory del metodo WdfUsbTargetPipeFormatRequestForRead del metodo ReadMemory .
Il driver deve specificare questo spazio buffer come handle WDFMEMORY per la memoria gestita dal framework. Il driver può eseguire una delle operazioni seguenti:
- Chiamare WdfMemoryCreate o WdfMemoryCreatePreallocated per creare un nuovo buffer di memoria, se si vuole che il driver passi un nuovo buffer alla destinazione di I/O.
- Chiamare WdfRequestRetrieveOutputMemory per ottenere un handle all'oggetto memory che rappresenta il buffer della richiesta di I/O ricevuto, se si vuole che il driver passi il contenuto del buffer alla destinazione I/O.
Più chiamate a WdfUsbTargetPipeFormatRequestForRead che usano la stessa richiesta non causano allocazioni di risorse aggiuntive. Pertanto, per ridurre la possibilità che WdfRequestCreate restituirà STATUS_INSUFFICIENT_RESOURCES, la funzione evtDriverDeviceAdd callback del driver può chiamare WdfRequestCreate per preallocare uno o più oggetti richiesta per un dispositivo. Il driver può successivamente riutilizzare (chiamare WdfRequestReuse), riformattare (chiamare WdfUsbTargetPipeFormatRequestForRead) e inviare nuovamente (chiamare WdfRequestSend) ogni oggetto richiesta senza rischiare un valore restituito STATUS_INSUFFICIENT_RESOURCES da una chiamata successiva a WdfRequestCreate. Tutte le chiamate successive a WdfUsbTargetPipeFormatRequestForRead per l'oggetto richiesta riutilizzato restituiranno STATUS_SUCCESS, se i valori dei parametri non cambiano. Se il driver non chiama lo stesso metodo di formattazione delle richieste ogni volta, è possibile allocare risorse aggiuntive.
Il framework imposta il flag di USBD_SHORT_TRANSFER_OK nel relativo FRAMEWORK interno. L'impostazione di questo flag consente all'ultimo pacchetto di un trasferimento dati di essere minore della dimensione massima del pacchetto.
Per informazioni sull'acquisizione di informazioni sullo stato dopo il completamento di una richiesta di I/O, vedere Recupero delle informazioni di completamento.
Per altre informazioni sul metodo WdfUsbTargetPipeFormatRequestForRead e sulle destinazioni di I/O USB, vedere Destinazioni di I/O USB.
Esempio
L'esempio di codice seguente proviene dal driver di esempio kmdf_fx2 . Questo esempio è una funzione di callback EvtIoRead che inoltra una richiesta di lettura a una pipe USB. L'esempio chiama WdfRequestRetrieveOutputMemory per ottenere il buffer di output della richiesta e quindi formatta la richiesta di lettura in modo che la richiesta possa essere inviata a una pipe USB. Successivamente, l'esempio registra una funzione di callback Di completamentoRoutine . Infine, invia la richiesta alla pipe USB.
VOID
OsrFxEvtIoRead(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN size_t Length
)
{
WDFUSBPIPE pipe;
NTSTATUS status;
WDFMEMORY reqMemory;
PDEVICE_CONTEXT pDeviceContext;
//
// First, validate input parameters.
//
if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
status = STATUS_INVALID_PARAMETER;
goto Exit;
}
pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
pipe = pDeviceContext->BulkReadPipe;
status = WdfRequestRetrieveOutputMemory(
Request,
&reqMemory
);
if (!NT_SUCCESS(status)){
goto Exit;
}
status = WdfUsbTargetPipeFormatRequestForRead(
pipe,
Request,
reqMemory,
NULL
);
if (!NT_SUCCESS(status)) {
goto Exit;
}
WdfRequestSetCompletionRoutine(
Request,
EvtRequestReadCompletionRoutine,
pipe
);
if (WdfRequestSend(
Request,
WdfUsbTargetPipeGetIoTarget(pipe),
WDF_NO_SEND_OPTIONS
) == FALSE) {
status = WdfRequestGetStatus(Request);
goto Exit;
}
Exit:
if (!NT_SUCCESS(status)) {
WdfRequestCompleteWithInformation(
Request,
status,
0
);
}
return;
}
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), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf),RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |
Vedi anche
WdfRequestCompleteWithInformation
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