DRIVER_CANCEL funzione di callback (wdm.h)

Articolo
02/29/2024

La routine Cancel annulla un'operazione di I/O.

Sintassi

DRIVER_CANCEL DriverCancel;

void DriverCancel(
  [in, out] _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp
)
{...}

Parametri

[in, out] DeviceObject

Puntatore fornito dal chiamante a una struttura DEVICE_OBJECT . Si tratta dell'oggetto dispositivo per il dispositivo di destinazione, creato in precedenza dalla routine AddDevice del driver.

[in, out] Irp

Puntatore fornito dal chiamante a una struttura IRP che descrive l'operazione di I/O da annullare.

Valore restituito

nessuno

Osservazioni

Quando un driver o un altro componente di sistema chiama IoCancelIrp, il gestore I/O chiama la routine Annulla dell'IRP, se ne è stato registrato uno per l'IRP.

Per registrare una routine Cancel per un'IRP, un driver può usare uno dei due metodi seguenti:

Un driver che fornisce una routine StartIo e usa la coda del dispositivo fornita da gestione I/O può specificare una routine Annulla quando si chiama IoStartPacket.
Un driver che crea e gestisce code di dispositivi supplementari può registrare una routine Annulla chiamando IoSetCancelRoutine.

È possibile registrare una sola routine Cancel per un'IRP alla volta.

Il gestore I/O chiama IoAcquireCancelSpinLock prima di chiamare la routine Cancel di un driver, quindi la routine Cancel deve chiamare IoReleaseCancelSpinLock a un certo punto. La routine non deve contenere il blocco di rotazione più lungo del necessario.

La routine Cancel viene eseguita in un contesto di thread arbitrario in IRQL = DISPATCH_LEVEL finché non chiama IoReleaseCancelSpinLock, che modifica il valore IRQL in un valore fornito dal chiamante. Il driver deve specificare Irp-CancelIrql> per questo valore.

La routine Annulla deve impostare il membro Stato del blocco di I/O su STATUS_CANCELLED e impostare il membro Information su zero. La routine deve quindi completare l'IRP specificato chiamando IoCompleteRequest.

Per informazioni dettagliate sull'implementazione della routine Cancel di un driver, vedere Annullamento di IRP.

Esempio

Per definire una routine di callback Cancel , è prima necessario specificare una dichiarazione di funzione che identifica il tipo di routine di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione usando i tipi di funzione callback consente l'analisi del codice per i driver, il verifica driver statico (SDV) e altri strumenti di verifica trovano errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una routine di callback Annulla denominata MyCancel, usare il tipo di DRIVER_CANCEL come illustrato in questo esempio di codice:

DRIVER_CANCEL MyCancel;

Implementare quindi la routine di callback come indicato di seguito:

_Use_decl_annotations_
VOID
  MyCancel(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp
    )
  {
      // Function body
  }

Il tipo di funzione DRIVER_CANCEL è definito nel file di intestazione Wdm.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_ garantisce che vengano usate le annotazioni applicate al tipo di funzione DRIVER_CANCEL nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo per i driver WDM. Per informazioni su _Use_decl_annotations_, vedere Annotazione del comportamento della funzione.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Desktop
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Chiamato in DISPATCH_LEVEL (vedere la sezione Osservazioni).

Condividi tramite