Funzione WdfUsbTargetPipeFormatRequestForRead (wdfusb.h)

Articolo
08/08/2023

[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
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente disponibile.
STATUS_INVALID_DEVICE_REQUEST	È 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.
STATUS_INTEGER_OVERFLOW	Offset specificato dal parametro Offset non valido.
STATUS_INVALID_BUFFER_SIZE	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.
STATUS_REQUEST_NOT_ACCEPTED	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 .

Per altre informazioni sull'inoltro di una richiesta di I/O, vedere Inoltro di richieste di I/O.

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.
Si noti che se il driver chiama WdfRequestRetrieveOutputMemory e passa l'handle di memoria a WdfUsbTargetPipeFormatRequestForRead, il driver non deve completare la richiesta di I/O ricevuta fino a quando il driver elimina, riutilizza o riformula il nuovo oggetto richiesta creato dal driver. (WdfUsbTargetPipeFormatRequestForRead incrementa il conteggio dei riferimenti dell'oggetto memoria. Eliminazione, riutilizzo o riformattamento di un oggetto request decrementa il numero di riferimenti dell'oggetto memoria.

Dopo aver chiamato WdfUsbTargetPipeFormatRequestForRead per formattare una richiesta di I/O, il driver deve chiamare WdfRequestSend per inviare la richiesta (in modo sincrono o asincrono) a una destinazione di 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)