EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE funzione di callback (wdfio.h)

  • Articolo

[Si applica a KMDF e UMDF]

La funzione di callback dell'evento EvtIoCanceledOnQueue di un driver informa il driver che deve completare una richiesta di I/O che il framework è stato rimosso da una coda di I/O.

Sintassi

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE EvtWdfIoQueueIoCanceledOnQueue;

void EvtWdfIoQueueIoCanceledOnQueue(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request
)
{...}

Parametri

[in] Queue

Handle per un oggetto coda di I/O.

[in] Request

Handle per un oggetto richiesta.

Valore restituito

nessuno

Osservazioni

Un driver registra una funzione di callback EvtIoCanceledOnQueue quando chiama il metodo WdfIoQueueCreate . Per altre informazioni sulla chiamata a WdfIoQueueCreate, vedere Creazione di code di I/O.

Se un driver registra una funzione di callback EvtIoCanceledOnQueue per una coda di I/O, il framework chiama la funzione di callback nelle situazioni seguenti:

  • Un gestore di richieste riceve una richiesta di I/O da una coda di I/O, il driver chiama WdfRequestForwardToIoQueue, WdfRequestForwardToParentDeviceIoQueue o WdfRequestRequeue per accodare nuovamente la richiesta alla coda di I/O per cui viene registrata la funzione di callback EvtIoCanceledOnQueue e l'operazione di I/O associata viene successivamente annullata.
  • La funzione di callback EvtIoInCallerContext del driver riceve una richiesta di I/O, il driver chiama WdfDeviceEnqueueRequest per passare nuovamente la richiesta al framework, il framework inserisce quindi la richiesta nella coda di I/O per cui viene registrata la funzione di callback EvtIoCanceledOnQueue e l'operazione di I/O associata viene successivamente annullata.
Dopo che il framework chiama la funzione di callback EvtIoCanceledOnQueue , il driver è proprietario dell'oggetto richiesta e deve completare la richiesta con un codice di stato appropriato, in EvtIoCanceledOnQueue o versione successiva. Quando il framework chiama EvtIoCanceledOnQueue, la richiesta è ancora associata alla coda di I/O, ma il driver non può rieseguere la richiesta. La proprietà della richiesta rimane con il driver anche se il driver non completa la richiesta in EvtIoCanceledOnQueue. Se il driver completa la richiesta dopo la restituzione di EvtIoCanceledOnQueue , non può chiamare WdfIoQueueFindRequest e WdfIoQueueRetrieveFoundRequest per riacquisire la proprietà della richiesta perché il driver ha già la proprietà della richiesta.

In genere, in EvtIoCanceledOnQueue il driver completa la richiesta di I/O con lo stato di completamento di STATUS_CANCELLED.

In alcuni casi, il driver potrebbe aver accodato in precedenza una richiesta di I/O a una coda manuale, ad esempio per attendere le informazioni. Ad esempio, in uno dei gestori di richieste, un driver potrebbe inserire una richiesta di I/O associata a una transazione DMA in sospeso in una coda manuale. In questo caso, il driver tenta di annullare la transazione DMA nel callback EvtIoCanceledOnQueue . A seconda dei risultati dell'operazione di annullamento, il driver completa la richiesta con uno stato appropriato, in EvtIoCanceledOnQueue o versione successiva.

Il framework non chiama la funzione di callback EvtIoCanceledOnQueue del driver per le richieste di I/O che il framework non ha mai recapitato al driver.

Il framework chiama una funzione di callback EvtIoCanceledOnQueue non appena determina che una richiesta di I/O è stata annullata, indipendentemente dal metodo di invio impostato dal driver per la coda di I/O. Di conseguenza, il framework può chiamare una funzione di callback EvtIoCanceledOnQueue per:

  • Richiesta in una coda che usa l'invio sequenziale, anche se il driver è attualmente proprietario di un'altra richiesta dalla coda.
  • Richiesta in una coda per la quale il driver ha impostato NumberOfPresentedRequests, anche se il driver è attualmente proprietario del numero massimo di richieste.
Per altre informazioni sulla funzione di callback EvtIoCanceledOnQueue , vedere Annullamento delle richieste di I/O.

La funzione di callback EvtIoCanceledOnQueue può essere chiamata in IRQL <= DISPATCH_LEVEL, a meno che il membro ExecutionLeveldella struttura WDF_OBJECT_ATTRIBUTES del dispositivo o del driver sia impostato su WdfExecutionLevelPassive.

Se IRQL è PASSIVE_LEVEL, il framework chiama la funzione di callback all'interno di un'area critica.

Esempio

Per definire una funzione di callback EvtIoCanceledOnQueue , è necessario innanzitutto fornire una dichiarazione di funzione che identifica il tipo di funzione di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione tramite i tipi di funzione di callback consente di analizzare il codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica di trovare errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Per definire una funzione di callback EvtIoCanceledOnQueue , è prima necessario fornire una dichiarazione di funzione necessaria per SDV e altri strumenti di verifica. L'esempio seguente è tratto dall'esempio di driver di smart card PCMCIA .

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE PscrEvtIoCanceledOnQueue;

Nell'esempio pcmcia smart card driver il driver usa una coda manuale per archiviare le richieste di notifica delle smart card in sospeso. Il driver fornisce una funzione di callback EvtIoCanceledOnQueue in cui il driver cancella il campo di notifica e completa la richiesta.

_Use_decl_annotations_
VOID
PscrEvtIoCanceledOnQueue(
    WDFQUEUE  Queue,
    WDFREQUEST  Request
    )

{
    PDEVICE_EXTENSION DeviceExtension;
    PSMARTCARD_EXTENSION smartcardExtension;

    DeviceExtension = GetDeviceExtension(WdfIoQueueGetDevice(Queue));
    smartcardExtension = (PSMARTCARD_EXTENSION) &DeviceExtension->SmartcardExtension;

    //KdPrint(("Cancelled on queue 0x%x\n", WdfRequestWdmGetIrp(Request)));

    InterlockedExchangePointer(
                             &(smartcardExtension->OsData->NotificationIrp),
                             NULL
                             );

    WdfRequestComplete(Request, STATUS_CANCELLED);
}

Il tipo di funzione EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE è definito nel file di intestazione Wdfio.h. Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations assicura che vengano utilizzate le annotazioni applicate al tipo di funzione EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo di funzione per i driver KMDF. Per informazioni sulle Use_decl_annotations, vedere Annotazione del comportamento della funzione.

Requisiti

Requisito Valore
Piattaforma di destinazione Universale
Versione KMDF minima 1.0
Versione UMDF minima 2,0
Intestazione wdfio.h (include Wdf.h)
IRQL <= DISPATCH_LEVEL (vedere la sezione Osservazioni)

Vedi anche

WdfIoQueueCreate

WdfRequestForwardToIoQueue