Funzione WdfUsbTargetPipeFormatRequestForUrb (wdfusb.h)

Articolo
08/08/2023

[Si applica solo a KMDF]

Il metodo WdfUsbTargetPipeFormatRequestForUrb compila una richiesta USB per una pipe USB specificata, usando i parametri di richiesta descritti da un oggetto COMPIL specificato, ma non invia la richiesta.

Sintassi

NTSTATUS WdfUsbTargetPipeFormatRequestForUrb(
                 WDFUSBPIPE        PIPE,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         UrbMemory,
  [in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);

Parametri

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] UrbMemory

Handle per un oggetto memoria del framework che contiene una struttura WM .

Se il driver precedentemente chiamato WdfUsbTargetDeviceCreateWithParameters per creare UsbDevice, il driver deve usare WdfUsbTargetDeviceCreateUrb o WdfUsbTargetDeviceCreateIsochUrb per creare l'oggetto DEVICE contenuto in questo oggetto memoria.

[in, optional] UrbMemoryOffset

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 iniziale dell'oggetto ROUTE all'interno della memoria specificata da EsegueMemory . Se questo puntatore è NULL, l'OGGETTO VERRÀ posizionato all'inizio della memoria DioMemory .

Valore restituito

WdfUsbTargetPipeFormatRequestForUrb 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
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente disponibile.
STATUS_INTEGER_OVERFLOW	Offset non valido per il parametro UsbMemoryOffset specificato.
STATUS_REQUEST_NOT_ACCEPTED	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 WdfUsbTargetPipeFormatRequestForUrb, seguito da WdfRequestSend, per inviare una richiesta USB in modo sincrono o asincrono. In alternativa, usare il metodo WdfUsbTargetPipeSendUrbSynchronously per inviare una richiesta in modo sincrono.

Il framework non esamina la richiesta USB. Se la richiesta modifica lo stato della pipe USB, il framework non sarà a conoscenza della modifica.

È possibile inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O oppure creare e inviare una nuova richiesta.

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 WdfUsbTargetPipeFormatRequestForUrb.

Per creare una nuova richiesta di I/O, chiamare WdfRequestCreate per preallocare un oggetto richiesta. Specificare l'handle di richiesta per il parametro Request del metodo WdfUsbTargetPipeFormatRequestForUrb. È possibile riutilizzare l'oggetto richiesta chiamando WdfRequestReuse, in modo che la funzione di callback EvtDriverDeviceAdd del driver possa preallocare gli oggetti richiesta per un dispositivo.

Dopo aver chiamato WdfUsbTargetPipeFormatRequestForUrb 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 WdfUsbTargetPipeFormatRequestForUrb 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 WdfUsbTargetPipeFormatRequestForUrb) e inviare di nuovo (chiamare WdfRequestSend) ogni oggetto richiesta senza rischiare un valore restituito STATUS_INSUFFICIENT_RESOURCES da una chiamata successiva a WdfRequestCreate. Tutte le chiamate successive a WdfUsbTargetPipeFormatRequestForUrb 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 WdfUsbTargetPipeFormatRequestForUrb e sulle destinazioni di I/O USB, vedi Destinazioni di I/O USB.

Esempio

Nell'esempio di codice seguente viene creato un oggetto memory che rappresenta un oggettoITEM. Nell'esempio viene quindi inizializzata l'istruzione CSV, viene formattata una richiesta USB che contiene l'istruzione CSV, viene registrata una funzione di callback CompletionRoutine e viene inviata la richiesta.

URB  urb;
PURB  pUrb = NULL;
WDFMEMORY  urbMemory
NTSTATUS status;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(struct _URB_GET_CURRENT_FRAME_NUMBER),
                         &urbMemory,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}

pUrb = WdfMemoryGetBuffer(
                          urbMemory,
                          NULL
                          );

pUrb->UrbHeader.Length = (USHORT) sizeof(struct _URB_GET_CURRENT_FRAME_NUMBER);
pUrb->UrbHeader.Function = URB_FUNCTION_GET_CURRENT_FRAME_NUMBER;
pUrb->UrbGetCurrentFrameNumber.FrameNumber = 0; 

status = WdfUsbTargetPipeFormatRequestForUrb(
                                             pipe,
                                             Request,
                                             urbMemory,
                                             NULL
                                             );
if (!NT_SUCCESS(status)) {
    goto Exit;
}
WdfRequestSetCompletionRoutine(
                               Request,
                               UrbCompletionRoutine,
                               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
Intestazione	wdfusb.h (include Wdfusb.h)
Libreria	Wdf01000.sys (vedere Controllo delle versioni della libreria framework).
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)