EVT_SPB_CONTROLLER_LOCK Rückruffunktion (spbcx.h)

Artikel
02/26/2024

Die EvtSpbControllerLock-Ereignisrückruffunktion eines SPB-Controllertreibers sperrt den SPB-Controller für den Zugriff auf ein einzelnes Zielgerät auf dem Bus.

Syntax

EVT_SPB_CONTROLLER_LOCK EvtSpbControllerLock;

void EvtSpbControllerLock(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target,
  [in] SPBREQUEST LockRequest
)
{...}

Parameter

[in] Controller

Ein WDFDEVICE-Handle für das Framework-Geräteobjekt , das den SPB-Controller darstellt.

[in] Target

Ein SPBTARGET-Handle für das Ziel für diese E/A-Anforderung. Das Ziel ist ein Peripheriegerät oder ein Port, das an den Bus angeschlossen ist. Die SPB-Frameworkerweiterung (SpbCx) hat dieses Handle zuvor dem Ziel im EvtSpbTargetConnect-Rückruf zugewiesen, der die Verbindung mit dem Ziel geöffnet hat.

[in] LockRequest

Ein SPBREQUEST-Handle für eine E/A-Steuerungsanforderung, um den Controller zu sperren. Ihr SPB-Controllertreiber muss diese Anforderung entweder durch Ausführen des angeforderten Vorgangs oder durch Zurückgeben eines Fehlers status abschließen. Weitere Informationen finden Sie unter Hinweise.

Rückgabewert

Keine

Bemerkungen

SpbCx verwaltet die E/A-Warteschlange für den SPB-Controller. Wenn der SPB-Controllertreiber eine EvtSpbControllerLock-Rückruffunktion registriert, ruft SpbCx diese Funktion auf, wenn ein Client (Peripherietreiber) des Controllers eine IOCTL_SPB_LOCK_CONTROLLER Anforderung an ein Ziel im Bus sendet. Der Wert des LockRequest-Parameters ist ein Handle, das diese Anforderung kapselt.

Die Funktionen EvtSpbControllerLock und EvtSpbControllerUnlock führen ergänzende Vorgänge aus. Beide Funktionen sind optional. Wenn Ihr SPB-Controllertreiber eine EvtSpbControllerUnlock-Funktion implementiert, muss der Treiber keine EvtSpbControllerLock-Funktion implementieren, kann dies jedoch tun. Wenn ihr SPB-Controllertreiber jedoch eine EvtSpbControllerLock-Funktion implementiert, muss er auch eine EvtSpbControllerUnlock-Funktion implementieren. Weitere Informationen finden Sie unter Hinweise in SPB_CONTROLLER_CONFIG.

Während die Sperre wirksam ist, darf der Controller keine Zugriffe auf Ziele auf dem Bus zulassen, die nicht auf das durch den LockRequest-Parameter festgelegte Ziel zugreifen.

Wenn der SPB-Controllertreiber den Modus seines Controllers ändern muss, um den normalen Zielauswahlmechanismus vorübergehend außer Kraft zu setzen, kann er dies während des EvtSpbControllerLock-Rückrufs tun. Wenn dieser Moduswechsel mit einer langen Verzögerung verbunden ist oder der Treiber auf einen Geräteunterbrechung warten muss, sollte der Treiber den Moduswechsel initiieren und dann ohne Verzögerung vom Rückruf zurückkehren. Später kann der Treiber den Sperrvorgang in einem Timer-DPC oder einem Interrupt-DPC abschließen.

Wenn der Sperrvorgang in einem DPC abgeschlossen wird, sollte der SPB-Controllertreiber zuvor alle Ressourcen zugeordnet haben, die er für den Sperrvorgang benötigt.

Ein EvtSpbControllerLock-Rückruf muss verhindern, dass eine Sperranforderung fehlschlägt. Wenn die Treiberüberprüfung aktiviert ist, löst ein solcher Fehler eine Prüferfalle aus, die dem Plug & Play-Manager meldet, dass der Controller fehlgeschlagen ist. SpbCx ignoriert den Fehler einer Sperranforderung und versucht nicht, den Fehler zu behandeln oder zu beheben.

Die EvtSpbControllerLock-Funktion gibt keinen Wert zurück. Stattdessen gibt der SPB-Controllertreiber die status des Sperrvorgangs im Abschluss status der E/A-Anforderung an, die durch den LockRequest-Parameter identifiziert wird. Legen Sie die status für die Vervollständigung auf STATUS_SUCCESS fest.

SpbCx ruft die Ereignisrückruffunktion EvtSpbControllerUnlock auf, um einen Controller zu entsperren, der zuvor durch einen EvtSpbControllerLock-Rückruf gesperrt wurde.

Um eine EvtSpbControllerLock-Rückruffunktion zu registrieren, rufen Sie die SpbDeviceInitialize-Methode auf .

Weitere Informationen zur EvtSpbControllerLock-Funktion finden Sie unter Behandeln Client-Implemented Sequenzen.

Beispiele

Um eine EvtSpbControllerLock-Rückruffunktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückruffunktion 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.

Wenn Sie beispielsweise eine EvtSpbControllerLock-Rückruffunktion mit dem Namen MyEvtSpbControllerLockdefinieren möchten, verwenden Sie den Funktionstyp EVT_SPB_CONTROLLER_LOCK, wie in diesem Codebeispiel gezeigt:

EVT_SPB_CONTROLLER_LOCK  MyEvtSpbControllerLock;

Implementieren Sie dann Ihre Rückruffunktion wie folgt:

_Use_decl_annotations_
VOID
  MyEvtSpbControllerLock(
    WDFDEVICE Controller,
    SPBTARGET Target,
    SPBREQUEST LockRequest
    )
{ ... }

Der EVT_SPB_CONTROLLER_LOCK Funktionstyp ist in der Spbcx.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, müssen Sie der Funktionsdefinition die anmerkung Use_decl_annotations hinzufügen. Die Use_decl_annotations-Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den EVT_SPB_CONTROLLER_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 KMDF-Treiber. Weitere Informationen zu Use_decl_annotations finden Sie unter Annotating Function Behavior.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Unterstützt ab Windows 8.
Zielplattform	Desktop
Kopfzeile	spbcx.h
IRQL	Wird unter IRQL <= DISPATCH_LEVEL aufgerufen.

Share via