EVT_SERCX2_SET_WAIT_MASK Rückruffunktion (sercx.h)

Artikel
10/30/2024

Die EvtSerCx2SetWaitMask Ereignisrückruffunktion wird von Version 2 der seriellen Framework-Erweiterung (SerCx2) aufgerufen, um den seriellen Controller so zu konfigurieren, dass eine Reihe von Hardwareereignissen überwacht wird, die durch eine Wartemaske angegeben werden.

Syntax

EVT_SERCX2_SET_WAIT_MASK EvtSercx2SetWaitMask;

void EvtSercx2SetWaitMask(
  [in] WDFDEVICE Device,
  [in] WDFREQUEST Request,
  [in] ULONG WaitMask
)
{...}

Parameter

[in] Device

Ein WDFDEVICE-Handle für das Framework-Geräteobjekt, das den seriellen Controller darstellt. Der serielle Controllertreiber hat dieses Objekt in seiner EvtDriverDeviceAdd Rückruffunktion erstellt. Weitere Informationen finden Sie unter SerCx2InitializeDevice.

[in] Request

Ein WDFREQUEST-Handle für das Framework-Anforderungsobjekt, das die IOCTL_SERIAL_SET_WAIT_MASK Anforderung darstellt.

[in] WaitMask

Die neue Wartemaske. Weitere Informationen finden Sie in den Hinweisen.

Rückgabewert

Nichts

Bemerkungen

Ihr serieller Controllertreiber kann diese Funktion als Option implementieren. Falls implementiert, registriert der Treiber die Funktion im Aufruf der SerCx2InitializeDevice Methode, die die Initialisierung des Framework-Geräteobjekts für den seriellen Controller beendet.

Wenn SerCx eine IOCTL_SERIAL_SET_WAIT_MASK Anforderung von einem Client empfängt, ruft der Anforderungshandler in SerCx2 den EvtSerCx2SetWaitMask--Funktion auf, um den Treiber zu benachrichtigen, dass sich die Wartemaske geändert hat. Wenn die Wartemaske nicht null ist, beginnt der Treiber sofort, die Ereignisse in der neuen Wartemaske zu überwachen, und verwirft alle alten Wartemasken, die möglicherweise in einem vorherigen EvtSerCx2SetWaitMask Aufruf bereitgestellt wurden. Wenn die neue Wartemaske null ist, verwirft der Fahrer einfach die alte Wartemaske und überwacht nicht mehr alle Wartemaskenereignisse. Weitere Informationen zu den Ereignistypen, die durch eine Wartemaske angegeben werden können, finden Sie unter SERIAL_EV_XXX.

Wenn der Treiber diese Funktion nicht implementiert, schlägt SerCx2 alle IOCTL_SERIAL_SET_WAIT_MASK Anforderungen mit Fehlerstatuscode STATUS_NOT_SUPPORTED fehl.

Um die Ereignisse im Warteformat zu überwachen, ermöglicht die EvtSerCx2SetWaitMask Funktion in der Regel Unterbrechungen für diese Ereignisse. Wenn später ein Ereignis in der Wartemaske erkannt wird, ruft der serielle Controllertreiber die SerCx2CompleteWait--Methode auf, um SerCx2 des Ereignisses zu benachrichtigen.

Die EvtSerCx2SetWaitMask Funktion ist für das Ausfüllen der IOCTL_SERIAL_SET_WAIT_MASK Anforderung verantwortlich, auf die der parameter Request verweist. Nachdem der serielle Controllertreiber die erforderlichen Unterbrechungen aktiviert hat, ruft er die WdfRequestComplete Methode auf und stellt als Eingabeparameter den parameterwert Request Parameterwert und einen Statuswert bereit, um anzugeben, ob die Anforderung erfolgreich war.

Bevor der serielle Controllertreiber WdfRequestComplete- aufruft, um die Anforderung abzuschließen, muss der Treiber alle Aufrufe an SerCx2CompleteWait abschließen, die aufgrund von Ereignissen in der alten Wartemaske möglicherweise noch ausstehen.

Nachdem ein Client zunächst eine logische Verbindung mit dem seriellen Port geöffnet hat und vor dem ersten EvtSerCx2SetWaitMask Aufruf, ist die Wartemaske effektiv null, und der serielle Controllertreiber überwacht keine SERIAL_EV_XXX Ereignisse.

SerCx2 schlägt eine IOCTL_SERIAL_SET_WAIT_MASK Anforderung mit einer Wartemaske fehl, die eines der folgenden SERIAL_EV_XXX Ereigniskennzeichnungen enthält:

SERIAL_EV_PERR
SERIAL_EV_RING
SERIAL_EV_RXFLAG

Daher enthält die für Die EvtSerCx2SetWaitMask Funktion bereitgestellte Wartemaske niemals eines der Ereigniskennzeichnungen in der vorherigen Liste.

Falls implementiert, sollte Ihre EvtSerCx2SetWaitMask--Funktion die folgenden Ereigniskennzeichnungen unterstützen:

SERIAL_EV_CTS
SERIAL_EV_BREAK
SERIAL_EV_ERR

Wenn der serielle Controller über einen Datensatz verfügt, der (DSR)-Signalleitung bereit ist, sollte die EvtSerCx2SetWaitMask-Funktion SERIAL_EV_DSR unterstützen. Als Option kann ein Treiber jedes der anderen Ereigniskennzeichnungen unterstützen, die in SERIAL_EV_XXXbeschrieben sind. Wenn das Warteformat ein Ereignis angibt, das der Treiber nicht unterstützt, sollte die EvtSerCx2SetWaitMask- funktion die Anforderung nicht bestehen und den Statuswert in der Anforderung auf STATUS_INVALID_PARAMETER festlegen.

Beispiele

Um eine EvtSerCx2SetWaitMask 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 EvtSerCx2SetWaitMask Rückruffunktion zu definieren, die MySetWaitmaskheißt, verwenden Sie den EVT_SERCX2_SET_WAIT_MASK Funktionstyp, wie in diesem Codebeispiel gezeigt:

EVT_SERCX2_SET_WAIT_MASK  MySetWaitmask;

Implementieren Sie dann die Rückruffunktion wie folgt:

_Use_decl_annotations_
VOID
  MySetWaitmask(
    WDFDEVICE  Device,
    WDFREQUEST Request,
    ULONG WaitMask
    )
  {...}

Der EVT_SERCX2_SET_WAIT_MASK 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_SET_WAIT_MASK 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.