Funzione WdfUsbTargetPipeFormatRequestForReset (wdfusb.h)

[Si applica a KMDF e UMDF]

Il metodo WdfUsbTargetPipeFormatRequestForReset compila una richiesta di reimpostazione per una pipe USB specificata, ma non invia la richiesta.

Sintassi

NTSTATUS WdfUsbTargetPipeFormatRequestForReset(
  [in] WDFUSBPIPE Pipe,
  [in] WDFREQUEST Request
);

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.

Valore restituito

WdfUsbTargetPipeFormatRequestForReset restituisce il valore di stato di completamento dell'I/O USB 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_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 WdfUsbTargetPipeFormatRequestForReset, seguito da WdfRequestSend, per inviare una richiesta di reimpostazione USB in modo sincrono o asincrono. In alternativa, usare il metodo WdfUsbTargetPipeResetSynchronously per inviare una richiesta in modo sincrono.

Prima che il driver chiami WdfRequestSend, deve chiamare WdfIoTargetStop e deve completare o annullare tutte le richieste di I/O inviate alla destinazione di I/O. Il driver non deve inviare richieste di I/O aggiuntive alla destinazione di I/O fino al completamento della richiesta di reimpostazione.

Quando un driver chiama WdfRequestSend, il framework invia una richiesta di URB_FUNCTION_RESET_PIPE alla destinazione di I/O. Per altre informazioni sulla reimpostazione di una pipe USB, vedere la specifica USB.

È possibile inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O oppure è possibile 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 WdfUsbTargetPipeFormatRequestForReset.

Per creare una nuova richiesta di I/O, chiamare WdfRequestCreate per preallocare un oggetto request. Specificare l'handle di richiesta per il parametro Request Del metodo WdfUsbTargetPipeFormatRequestForReset. È possibile riutilizzare l'oggetto request chiamando WdfRequestReuse. La funzione di callback EvtDriverDevice del driver può preallocare gli oggetti di richiesta per un dispositivo.

Dopo aver chiamato WdfUsbTargetPipeFormatRequestForReset 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 WdfUsbTargetPipeFormatRequestForReset 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), riformatare (chiamare WdfUsbTargetPipeFormatRequestForReset) 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 WdfUsbTargetPipeFormatRequestForReset 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 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 WdfUsbTargetPipeFormatRequestForReset e sulle destinazioni di I/O USB, vedere Destinazioni di I/O USB.

Esempio

Nell'esempio di codice seguente viene formattata una richiesta di reimpostazione per una pipe USB, registra una funzione di callback di CompletamentoRoutine e invia la richiesta.

status = WdfUsbTargetPipeFormatRequestForReset(
                                               pipe,
                                               Request
                                               );
if (!NT_SUCCESS(status)) {
    goto Exit;
}

WdfRequestSetCompletionRoutine(
                               Request,
                               AbortCompletionRoutine,
                               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), RequestForUrbXrb(kmdf),RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Vedi anche

WdfRequestSend

WdfUsbInterfaceGetConfiguredPipe