EVT_SPB_TARGET_CONNECT Rückruffunktion (spbcx.h)

Artikel
08/07/2023

Die EvtSpbTargetConnect-Ereignisrückruffunktion eines SPB-Controllertreibers öffnet eine Verbindung mit einem Zielgerät auf dem Bus.

Syntax

EVT_SPB_TARGET_CONNECT EvtSpbTargetConnect;

NTSTATUS EvtSpbTargetConnect(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target
)
{...}

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 zu öffnende Ziel. Das Ziel ist ein Peripheriegerät oder ein Port, das an den Bus angeschlossen ist.

Rückgabewert

EvtSpbTargetConnect gibt STATUS_SUCCESS zurück, wenn der Treiber die Verbindung mit dem Ziel erfolgreich öffnet. Andernfalls gibt die Funktion einen entsprechenden NTSTATUS-Fehlercode zurück.

Hinweise

Die Implementierung dieser Funktion durch den SPB-Controllertreiber ist optional.

Die SPB-Frameworkerweiterung (SpbCx) verwaltet die E/A-Warteschlange für den SPB-Controller. Wenn der SPB-Controllertreiber eine EvtSpbTargetConnect-Rückruffunktion registriert, ruft SpbCx diese Funktion auf, wenn ein Client (Peripherietreiber) des Controllers eine IRP_MJ_CREATE Anforderung sendet, um eine Verbindung mit einem Zielgerät auf dem Bus zu öffnen. Wenn die EvtSpbTargetConnect-Funktion einen Fehlercode zurückgibt, schlägt SpbCx die IRP_MJ_CREATE-Anforderung fehl. Ein Client, der erfolgreich eine Verbindung mit einem Ziel öffnet, hat exklusiven Zugriff auf das Ziel, bis die Verbindung geschlossen wird.

Rufen Sie die SpbTargetGetConnectionParameters-Methode auf, um die Verbindungsparameter für das Zielgerät abzurufen. Ein SPB-Controllertreiber ruft diese Methode in der Regel über die EvtSpbTargetConnect-Funktion des Treibers auf. SpbTargetGetConnectionParameters schreibt die Verbindungsparameter in eine vom Aufrufer bereitgestellte SPB_CONNECTION_PARAMETERS-Struktur . Das ConnectionParameters-Element dieser Struktur ist ein Zeiger auf einen Puffer, der die Verbindungseinstellungen für das Zielgerät enthält. Der Treiber verwendet diese Einstellungen, um den SPB-Controller für die Kommunikation mit dem Gerät zu konfigurieren. Weitere Informationen finden Sie unter Abrufen der Verbindungseinstellungen für ein Gerät.

Die Rückruffunktion EvtSpbTargetConnect wird synchron aus dem Kontext des Clientthreads aufgerufen, der die Verbindung mit dem Ziel anfordert.

SpbCx ruft die Rückruffunktion EvtSpbTargetDisconnect auf, um eine Zielverbindung zu schließen, die zuvor durch einen EvtSpbTargetConnect-Rückruf geöffnet wurde.

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

Beispiele

Um eine EvtSpbTargetConnect-Rückruffunktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückruffunktion identifiziert. 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 Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine EvtSpbTargetConnect-Rückruffunktion namens MyEvtSpbTargetConnectzu definieren, verwenden Sie den EVT_SPB_TARGET_CONNECT Funktionstyp, wie in diesem Codebeispiel gezeigt:

EVT_SPB_TARGET_CONNECT  MyEvtSpbTargetConnect;

Implementieren Sie dann Ihre Rückruffunktion wie folgt:

_Use_decl_annotations_
NTSTATUS
  MyEvtSpbTargetConnect(
    WDFDEVICE Controller,
    SPBTARGET Target
    )
{ ... }

Der EVT_SPB_TARGET_CONNECT Funktionstyp ist in der Headerdatei Spbcx.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzu. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den EVT_SPB_TARGET_CONNECT 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 Verhalten von Funktionen mit Anmerkungen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Wird ab Windows 8 unterstützt.
Zielplattform	Desktop
Kopfzeile	spbcx.h
IRQL	Wird bei PASSIVE_LEVEL aufgerufen.