EVT_SERCX_WAITMASK Rückruffunktion (sercx.h)

Artikel
02/26/2024

Die Ereignisrückruffunktion EvtSerCxWaitmask konfiguriert den seriellen Controller so, dass die Ereignisse in einer Wartemaske überwacht werden. Hierbei handelt es sich um einen Bitmaskenwert, der eine Reihe von Hardwareereignissen angibt.

Syntax

EVT_SERCX_WAITMASK EvtSercxWaitmask;

NTSTATUS EvtSercxWaitmask(
  [in] WDFDEVICE Device
)
{...}

Parameter

[in] Device

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

Rückgabewert

Die EvtSerCxWaitmask-Funktion gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Andernfalls wird ein entsprechender Fehler status Code zurückgegeben.

Hinweise

Der serielle Controllertreiber implementiert diese Rückruffunktion. Die Serial Framework-Erweiterung (SerCx) ruft diese Funktion auf, um den Treiber zu benachrichtigen, wenn sich die Wartemaske ändert. Während dieses Aufrufs ruft die EvtSerCxWaitmask-Funktion die SerCxGetWaitMask-Methode auf, um die neue Wartemaske abzurufen. Der Treiber beginnt sofort mit der Überwachung der Ereignisse in der neuen Wartemaske und verwirft alle alten Wartemasken, die möglicherweise in einem vorherigen EvtSerCxWaitmask-Aufruf bereitgestellt wurden. Wenn die neue Wartemaske null ist, verwirft der Treiber einfach die alte Wartemaske und überwacht keine Wartemaskenereignisse mehr.

Wenn SerCx eine IOCTL_SERIAL_SET_WAIT_MASK Anforderung von einem Client empfängt, ruft der Anforderungshandler in SerCx die EvtSerCxWaitmask-Funktion auf, um die neue Wartemaske festzulegen. Weitere Informationen zu den Ereignistypen, die durch eine Wartemaske angegeben werden können, finden Sie unter SERIAL_EV_XXX.

Die EvtSerCxWaitmask-Funktion konfiguriert die Hardware des seriellen Controllers, um die Ereignisse in der neuen Wartemaske zu überwachen. In der Regel aktiviert die Funktion Interrupts für diese Ereignisse. Nach dem Konfigurieren der Hardware sollte die Funktion sofort zurückgegeben werden, ohne auf ein Ereignis in der Wartemaske zu warten.

Wenn später ein Ereignis in der Wartemaske einen Interrupt verursacht, plant der ISR im seriellen Controllertreiber die Ausführung einer DPC-Funktion. Diese DPC-Funktion ruft die SerCxCompleteWait-Methode auf, um SerCx über das Ereignis zu benachrichtigen.

Nachdem ein Client eine Verbindung mit dem seriellen Port und vor dem ersten EvtSerCxWaitmask-Aufruf hergestellt hat, ist die Wartemaske effektiv null, und der Treiber des seriellen Controllers überwacht keine SERIAL_EV_XXX-Ereignisse .

Um eine EvtSerCxWaitmask-Rückruffunktion zu registrieren, ruft der Controllertreiber während des EvtDriverDeviceAdd-Rückrufs die SerCxInitialize-Methode auf.

Beispiele

Der Funktionstyp für diesen Rückruf wird in Sercx.h wie folgt deklariert.

typedef NTSTATUS
  EVT_SERCX_WAITMASK(
    __in WDFDEVICE Device
    );

Um eine EvtSerCxWaitmask-Rückruffunktion mit dem Namen MyEvtSerCxWaitmaskzu definieren, müssen Sie zunächst wie folgt eine Funktionsdeklaration bereitstellen, die für die statische Treiberüberprüfung (Static Driver Verifier , SDV) und andere Überprüfungstools erforderlich ist.

EVT_SERCX_WAITMASK MyEvtSerCxWaitmask;

Implementieren Sie dann Ihre Rückruffunktion wie folgt.

NTSTATUS
  MyEvtSerCxWaitmask(
    __in WDFDEVICE Device
    )
{ ... }

Weitere Informationen zu SDV-Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für KMDF-Treiber.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 8.
Zielplattform	Desktop
Kopfzeile	sercx.h
IRQL	Aufgerufen am IRQL <= DISPATCH_LEVEL