IO_CSQ_ACQUIRE_LOCK Rückruffunktion (wdm.h)

Artikel
02/27/2024

Die CsqAcquireLock-Routine wird vom System verwendet, um die Sperre für eine vom Treiber implementierte, abbruchsichere IRP-Warteschlange abzurufen.

Syntax

IO_CSQ_ACQUIRE_LOCK IoCsqAcquireLock;

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

Parameter

[in] Csq

Zeiger auf die IO_CSQ-Struktur für die abbruchsichere IRP-Warteschlange.

[out] Irql

Zeiger auf eine Variable, die von der CsqAcquireLock-Routine zum Speichern des aktuellen IRQL verwendet werden kann. Das System übergibt den gespeicherten Wert CsqReleaseLock , wenn es die Sperre freigibt.

Rückgabewert

Keine

Bemerkungen

Der Treiber gibt die CsqAcquireLock-Routine für eine abbruchsichere IRP-Warteschlange an, wenn die IO_CSQ-Struktur der Warteschlange initialisiert wird. Der Treiber gibt die Routine als CsqAcquireLock-Parameter von IoCsqInitialize oder IoCsqInitializeEx an, wenn IO_CSQ initialisiert wird. Weitere Informationen finden Sie unter Cancel-Safe IRP-Warteschlangen.

Das System ruft diese Routine auf, um eine Sperre für die IRP-Warteschlange des Treibers zu erhalten, bevor versucht wird, ein IRP aus der Warteschlange einzufügen oder daraus zu entfernen. Das System ruft die CsqReleaseLock-Routine auf, um die Sperre freizugeben.

Wenn der Treiber eine Drehsperre verwendet, um sperren für die Warteschlange zu implementieren, muss er die aktuelle IRQL für den Zeitpunkt speichern, für den er die Spinsperre freigibt. Das System übergibt einen Zeiger auf eine IRQL-Variable, die der Treiber zum Speichern des aktuellen IRQL verwenden kann. Das System übergibt den gespeicherten Wert als Irql-Parameter an CsqReleaseLock , wenn die Sperre freigegeben wird. Andernfalls kann der Treiber den Irql-Parameter ignorieren. Informationen zu Spinsperren finden Sie unter Spin Locks.

Treiber können einen beliebigen Sperrmechanismus verwenden, um die Warteschlange zu sperren, z. B. Mutexe. Weitere Informationen zu Mutexes finden Sie unter Mutex-Objekte.

Beispiele

Um eine CsqAcquireLock-Rückrufroutine zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückrufroutine identifiziert, die Sie definieren. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine CsqAcquireLock-Rückrufroutine mit dem Namen MyCsqAcquireLockzu definieren, verwenden Sie den typ IO_CSQ_ACQUIRE_LOCK, wie in diesem Codebeispiel gezeigt:

IO_CSQ_ACQUIRE_LOCK MyCsqAcquireLock;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

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

Der IO_CSQ_ACQUIRE_LOCK Funktionstyp ist in der Wdm.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie die _Use_decl_annotations_ Anmerkung ihrer Funktionsdefinition hinzu. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den IO_CSQ_ACQUIRE_LOCK Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für WDM-Treiber. Informationen zu _Use_decl_annotations_finden Sie unter Verhalten von Funktionen mit Anmerkungen.

Anforderungen

Anforderung	Wert
Zielplattform	Desktop
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Weitere Informationen finden Sie im Abschnitt mit den Hinweisen.