Funzione WdfUsbTargetPipeFormatRequestForWrite (wdfusb.h)
[Si applica a KMDF e UMDF]
Il metodo WdfUsbTargetPipeFormatRequestForWrite compila una richiesta di scrittura per una pipe di output USB, ma non invia la richiesta.
Sintassi
NTSTATUS WdfUsbTargetPipeFormatRequestForWrite(
[in] WDFUSBPIPE Pipe,
[in] WDFREQUEST Request,
[in, optional] WDFMEMORY WriteMemory,
[in, optional] PWDFMEMORY_OFFSET WriteOffset
);
Parametri
[in] Pipe
Handle per un oggetto pipe del framework ottenuto chiamando WdfUsbInterfaceGetConfiguredPipe.
[in] Request
Handle per un oggetto richiesta del framework. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
[in, optional] WriteMemory
Handle per un oggetto memoria del framework. Questo oggetto rappresenta un buffer che contiene dati che verranno inviati alla pipe. Per altre informazioni su questo buffer, vedere la sezione Osservazioni seguente.
[in, optional] WriteOffset
Puntatore a una struttura WDFMEMORY_OFFSET allocata dal chiamante che fornisce valori facoltativi di offset di byte e lunghezza. Il framework usa questi valori per determinare l'indirizzo e la lunghezza iniziale, all'interno del buffer di scrittura, per il trasferimento dei dati. Se questo puntatore è NULL, il trasferimento dei dati inizia all'inizio del buffer e le dimensioni del trasferimento sono le dimensioni del buffer.
Valore restituito
WdfUsbTargetPipeFormatRequestForWrite restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe 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. |
|
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 WdfUsbTargetPipeFormatRequestForWrite, seguito da WdfRequestSend, per inviare richieste di scrittura in modo sincrono o asincrono. In alternativa, usare il metodo WdfUsbTargetPipeWriteSynchronously per inviare richieste di scrittura in modo sincrono.
La pipe specificata deve essere una pipe di output 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 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 del metodo Request WdfUsbTargetPipeFormatRequestForWrite.
-
Usare il buffer di input della richiesta ricevuta per il parametro WriteMemory del metodo WdfUsbTargetPipeFormatRequestForWrite.
Il driver deve chiamare WdfRequestRetrieveInputMemory per ottenere un handle a un oggetto memoria del framework che rappresenta il buffer di input della richiesta e usare tale handle come valore per WriteMemory.
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 richiesta e specificare il relativo handle per il parametro Request del metodo Request WdfUsbTargetPipeFormatRequestForWrite.
Chiamare WdfRequestCreate per preallocare uno o più oggetti richiesta. È possibile riutilizzare questi oggetti richiesta chiamando WdfRequestReuse. La funzione di callback EvtDriverDeviceAdd del driver può preallocare oggetti richiesta per un dispositivo.
-
Specificare lo spazio del buffer e specificare l'handle del buffer per il parametro WriteMemory del metodo WdfUsbTargetPipeFormatRequestForWrite.
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 WdfRequestRetrieveInputMemory per ottenere un handle per l'oggetto memoria che rappresenta il buffer della richiesta di I/O ricevuta, se si desidera che il driver passi il contenuto del buffer alla destinazione di I/O.
Più chiamate a WdfUsbTargetPipeFormatRequestForWrite che usano la stessa richiesta non causano allocazioni di risorse aggiuntive. Pertanto, per ridurre la probabilità che WdfRequestCreate restituisca STATUS_INSUFFICIENT_RESOURCES, la funzione di callback EvtDriverDeviceAdd del driver può chiamare WdfRequestCreate per preallocare uno o più oggetti richiesta per un dispositivo. Il driver può successivamente riutilizzare (chiamare WdfRequestReuse), riformattare (chiamare WdfUsbTargetPipeFormatRequestForWrite) 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 WdfUsbTargetPipeFormatRequestForWrite 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.
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 WdfUsbTargetPipeFormatRequestForWrite e sulle destinazioni di I/O USB, vedere Destinazioni di I/O USB.
Esempio
L'esempio di codice seguente è tratto dal driver di esempio kmdf_fx2 . Questo esempio è una funzione di callback EvtIoWrite che inoltra una richiesta di scrittura a una pipe USB. L'esempio chiama WdfRequestRetrieveInputMemory per ottenere il buffer di input della richiesta e quindi formatta la richiesta di scrittura in modo che la richiesta possa essere inviata a una pipe USB. L'esempio registra quindi una funzione di callback CompletionRoutine . Infine, invia la richiesta alla pipe USB.
VOID
OsrFxEvtIoWrite(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN size_t Length
)
{
NTSTATUS status;
WDFUSBPIPE pipe;
WDFMEMORY reqMemory;
PDEVICE_CONTEXT pDeviceContext;
if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
status = STATUS_INVALID_PARAMETER;
goto Exit;
}
pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
pipe = pDeviceContext->BulkWritePipe;
status = WdfRequestRetrieveInputMemory(
Request,
&reqMemory
);
if (!NT_SUCCESS(status)){
goto Exit;
}
status = WdfUsbTargetPipeFormatRequestForWrite(
pipe,
Request,
reqMemory,
NULL
);
if (!NT_SUCCESS(status)) {
goto Exit;
}
WdfRequestSetCompletionRoutine(
Request,
EvtRequestWriteCompletionRoutine,
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) |