Funzione WdfUsbTargetPipeFormatRequestForAbort (wdfusb.h)

[Si applica a KMDF e UMDF]

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

Sintassi

NTSTATUS WdfUsbTargetPipeFormatRequestForAbort(
  [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

WdfUsbTargetPipeFormatRequestForAbort restituisce il valore di stato di completamento della destinazione di 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_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 WdfUsbTargetPipeFormatRequestForAbort, seguito da WdfRequestSend, per inviare una richiesta di interruzione USB in modo sincrono o asincrono. In alternativa, usare il metodo WdfUsbTargetPipeAbortSynchronously per inviare una richiesta in modo sincrono.

Una richiesta di interruzione USB causa l'annullamento di tutte le richieste di I/O inviate a una pipe del driver. Quando un driver chiama WdfRequestSend, il framework invia una richiesta di URB_FUNCTION_ABORT_PIPE alla destinazione di I/O. Per altre informazioni sull'annullamento delle operazioni su una pipe USB (denominata anche "interruzione di una pipe"), 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 WdfUsbTargetPipeFormatRequestForAbort.

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 WdfUsbTargetPipeFormatRequestForAbort. È 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 WdfUsbTargetPipeFormatRequestForAbort 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 WdfUsbTargetPipeFormatRequestForAbort 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 WdfUsbTargetPipeFormatRequestForAbort) 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 WdfUsbTargetPipeFormatRequestForAbort 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 WdfUsbTargetPipeFormatRequestForAbort e sulle destinazioni DI I/O USB, vedere Destinazioni di I/O USB.

Esempio

L'esempio di codice seguente formatta una richiesta di interruzione per una pipe USB, registra una funzione di callback di CompletamentoRoutine e invia la richiesta.

status = WdfUsbTargetPipeFormatRequestForAbort(
                                               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

WdfUsbInterfaceGetConfiguredPipe