IO_CSQ_ACQUIRE_LOCK Rückruffunktion (wdm.h)

Artikel
02/07/2025

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 Warteschlange mit abbruchsicheren IRP-Adressen.

[out] Irql

Zeiger auf eine Variable, mit der die CsqAcquireLock- Routine die aktuelle IRQL speichern kann. Das System übergibt den gespeicherten Wert CsqReleaseLock, wenn er die Sperre loslässt.

Rückgabewert

Nichts

Bemerkungen

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

Das System ruft diese Routine auf, um eine Sperre in der 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 zum Implementieren der Sperre für die Warteschlange verwendet, muss er die aktuelle IRQL speichern, wenn sie die Drehungssperre loslässt. Das System übergibt einen Zeiger an 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 Drehsperren finden Sie unter Spin Locks.

Treiber können jeden Sperrmechanismus verwenden, um die Warteschlange zu sperren, z. B. Mutexes. Weitere Informationen zu Mutexes finden Sie unter Mutex Objects.

Beispiele

Um eine CsqAcquireLock- Rückrufroutine zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückrufroutine identifiziert. Windows stellt eine Reihe von Rückruffunktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine CsqAcquireLock- Rückrufroutine zu definieren, die MyCsqAcquireLockheißt, verwenden Sie den IO_CSQ_ACQUIRE_LOCK Typ, 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 wird in der Wdm.h-Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die _Use_decl_annotations_ Anmerkung hinzufügen. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen, die auf den IO_CSQ_ACQUIRE_LOCK Funktionstyp in der Headerdatei angewendet werden, verwendet 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 Annotating Function Behavior.