EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START Rückruffunktion (sercx.h)

Artikel
10/30/2024

Die EvtSerCx2CustomReceiveTransactionStart Ereignisrückruffunktion wird von Version 2 der seriellen Framework-Erweiterung (SerCx2) aufgerufen, um eine benutzerdefinierte Empfangstransaktion zu starten.

Syntax

EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START EvtSercx2CustomReceiveTransactionStart;

void EvtSercx2CustomReceiveTransactionStart(
  [in] SERCX2CUSTOMRECEIVETRANSACTION CustomReceiveTransaction,
  [in] WDFREQUEST Request,
  [in] PMDL Mdl,
  [in] ULONG Offset,
  [in] ULONG Length
)
{...}

Parameter

[in] CustomReceiveTransaction

Ein SERCX2CUSTOMRECEIVETRANSACTION Handle für ein benutzerdefiniertes Empfangstransaktionsobjekt. Der serielle Controllertreiber hat zuvor den SerCx2CustomReceiveTransactionCreate Methode aufgerufen, um dieses Objekt zu erstellen.

[in] Request

Ein Handle zum Framework-Anforderungsobjekt, das der benutzerdefinierten Empfangstransaktion zugeordnet ist. Der Treiber ist für die Durchführung dieser Anforderung verantwortlich. Diese Anforderung ist möglicherweise nicht die vom Client gesendete IRP_MJ_READ Anforderung, daher sollte der serielle Controllertreiber nicht versuchen, diese Anforderung für den Zugriff auf den Lesepuffer zu verwenden. Diese Anforderung wird in erster Linie für die Abbruch-, Abschluss- und Warteschlangenweiterleitung (falls erforderlich) verwendet. Um auf den Lesepuffer für die Leseanforderung des Clients zuzugreifen, verwenden Sie die Parameter Mdl, Offsetund Length Parameter.

[in] Mdl

Ein Zeiger auf eine MDL-, die die Speicherseiten beschreibt, die vom Lesepuffer für die benutzerdefinierte Empfangstransaktion überspannt sind. Die Punkt-/Gather-Liste für die Datenübertragung verwendet den Bereich dieses Speichers, der durch die parameter Offset und Length angegeben wird.

[in] Offset

Der Startoffset für die Datenübertragung. Dieser Parameter ist ein Byte-Offset vom Anfang des Pufferbereichs, der von der MDL beschrieben wird. Wenn die MDL insgesamt N Bytes Pufferraum angibt, befinden sich mögliche Werte von Offset im Bereich 0 bis N-1.

[in] Length

Die Größe der Datenübertragung in Byte. Wenn die MDL insgesamt N Bytes Pufferraum angibt, befinden sich mögliche Werte Length im Bereich 1 bis N–Offset.

Rückgabewert

Nichts

Bemerkungen

Der serielle Controllertreiber muss diese Funktion implementieren, wenn ein objekt für die benutzerdefinierte Empfangstransaktion erstellt wird. Der Treiber registriert die Funktion im SerCx2CustomReceiveTransactionCreate Aufruf, der dieses Objekt erstellt.

Nachdem SerCx2 den EvtSerCx2CustomReceiveTransactionStart--Funktion aufruft, initiiert der serielle Controllertreiber die Transaktion, indem der benutzerdefinierte Datenübertragungsmechanismus programmiert wird, um Daten aus dem empfangenen FIFO in der seriellen Controllerhardware in den Puffer in der Leseanforderung zu verschieben. Sofern die Anforderung nicht sofort abgeschlossen werden kann, muss der Treiber vor dem zurückgeben der EvtSerCx2CustomReceiveTransactionStart-Funktion eine Methode wie WdfRequestMarkCancelableEx- aufrufen, um die Anforderung als abbruchfähig zu kennzeichnen.

Nachdem die EvtSerCx2CustomReceiveTransactionStart Funktion die Transaktion gestartet hat, ruft SerCx2 regelmäßig die EvtSerCx2CustomReceiveTransactionQueryProgress Ereignisrückruffunktion auf, um den Fortschritt des seriellen Controllertreibers bei der Durchführung dieser Transaktion zu überwachen. Nachdem die Transaktion abgeschlossen ist und der Treiber die ausstehende Leseanforderung abgeschlossen hat, ruft SerCx2 die EvtSerCx2CustomReceiveTransactionCleanup Ereignisrückruffunktion auf, wenn der Treiber diese Funktion implementiert.

Wenn der serielle Controllertreiber einen EvtSerCx2CustomReceiveTransactionInitialize Ereignisrückruffunktion implementiert, ruft SerCx2 diese Funktion auf, bevor die EvtSerCx2CustomReceiveTransactionStart-Funktion aufgerufen wird. Unmittelbar vor dem EvtSerCx2CustomReceiveTransactionStart Aufruf, und nach dem EvtSerCx2CustomReceiveTransactionInitialize Aufruf wird der Timer gestartet, der erkennt, ob die Leseanforderung timeout ist. Weitere Informationen finden Sie in der Diskussion über totale Timeouts in SERIAL_TIMEOUTS.

Wenn es sich bei dem benutzerdefinierten Datenübertragungsmechanismus um ein Busmaster-DMA-Gerät handelt, die EvtSerCx2CustomReceiveTransactionStart--Funktion kann eine Methode wie WdfDmaTransactionInitializeUsingOffset- aufrufen, um eine DMA-Transaktion zu initiieren, die den lesepuffer verwendet, der vom Mdl, Offsetund Length Parametern verwendet wird.

Wenn das vom parameter Request Parameter identifizierte Anforderungsobjekt Speicher für einen privaten Kontext enthält, wird dieser Speicher möglicherweise nicht initialisiert, wenn der serielle Controllertreiber zum ersten Mal auf den Kontext zugreift. Beim ersten Zugriff sollte der Treiber den Kontext in der Regel mit Nullen füllen und bei Bedarf explizit alle Felder im Kontext festlegen, für die nichtzero-Anfangswerte erforderlich sind.

Weitere Informationen finden Sie unter SerCx2 Custom-Receive Transactions.

Beispiele

Um eine EvtSerCx2CustomReceiveTransactionStart Rückruffunktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der rückruffunktion identifiziert, die Sie definieren. 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 EvtSerCx2CustomReceiveTransactionStart Rückruffunktion zu definieren, die MyCustomReceiveTransactionStartbenannt ist, verwenden Sie den funktionstyp EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START, wie in diesem Codebeispiel gezeigt:

EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START  MyCustomReceiveTransactionStart;

Implementieren Sie dann die Rückruffunktion wie folgt:

_Use_decl_annotations_
VOID
  MyCustomReceiveTransactionStart(
    SERCX2CUSTOMRECEIVETRANSACTION  CustomReceiveTransaction,
    WDFREQUEST  Request,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  Length
    )
  {...}

Der EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START Funktionstyp wird in der Headerdatei Sercx.h 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 Funktionstyp EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START 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 KMDF-Treiber. Weitere Informationen zu Use_decl_annotationsfinden Sie unter Annotating Function Behavior.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Verfügbar ab Windows 8.1.
Zielplattform-	Desktop
Header-	sercx.h
IRQL-	Wird bei IRQL <= DISPATCH_LEVEL aufgerufen.