IO_CSQ_ACQUIRE_LOCK funzione di callback (wdm.h)

Articolo
03/08/2023

La routine CsqAcquireLock viene usata dal sistema per acquisire il blocco per una coda IRP implementata dal driver.

Sintassi

IO_CSQ_ACQUIRE_LOCK IoCsqAcquireLock;

void IoCsqAcquireLock(
  [in]  PIO_CSQ Csq,
  [out] PKIRQL Irql
)
{...}

Parametri

[in] Csq

Puntatore alla struttura di IO_CSQ per la coda IRP annullata.

[out] Irql

Puntatore a una variabile che la routine CsqAcquireLock può usare per archiviare l'irQL corrente. Il sistema passa il valore archiviato CsqReleaseLock quando rilascia il blocco.

Valore restituito

nessuno

Osservazioni

Il driver specifica la routine CsqAcquireLock per una coda IRP annullata quando inizializza la struttura di IO_CSQ della coda. Il driver specifica la routine come parametro CsqAcquireLock di IoCsqInitialize o IoCsqInitializeEx quando inizializza IO_CSQ. Per altre informazioni, vedere Code IRP cancel-safe.

Il sistema chiama questa routine per acquisire un blocco nella coda IRP del driver prima di tentare di inserire o rimuovere un'IRP dalla coda. Il sistema chiama la routine CsqReleaseLock per rilasciare il blocco.

Se il driver usa un blocco spin per implementare il blocco per la coda, deve archiviare l'oggetto IRQL corrente per quando rilascia il blocco di rotazione. Il sistema passa un puntatore a una variabile IRQL che il driver può usare per archiviare l'IRQL corrente. Il sistema passa il valore archiviato come parametro Irql a CsqReleaseLock quando rilascia il blocco. In caso contrario, il driver può ignorare il parametro Irql . Per informazioni sui blocchi di spin, vedere Blocchi spin.

I driver possono usare qualsiasi meccanismo di blocco per bloccare la coda, ad esempio i mutex. Per altre informazioni sui mutex, vedere Oggetti Mutex.

Esempio

Per definire una routine di callback csqAcquireLock , è prima necessario fornire 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 csqAcquireLock denominata MyCsqAcquireLock, usare il tipo di IO_CSQ_ACQUIRE_LOCK come illustrato nell'esempio di codice seguente:

IO_CSQ_ACQUIRE_LOCK MyCsqAcquireLock;

Implementare quindi la routine di callback come indicato di seguito:

_Use_decl_annotations_
VOID 
 MyCsqAcquireLock(
    PIO_CSQ  Csq,
    PKIRQL  Irql
    )
  {
      // Function body
  }

Il tipo di funzione IO_CSQ_ACQUIRE_LOCK viene 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 IO_CSQ_ACQUIRE_LOCK 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.