EVT_SERCX2_CONTROL Rückruffunktion (sercx.h)
Die EvtSerCx2Control Ereignisrückruffunktion wird von Version 2 der seriellen Framework-Erweiterung (SerCx2) aufgerufen, um eine serielle E/A-Steuerelementanforderung zu verarbeiten.
Syntax
EVT_SERCX2_CONTROL EvtSercx2Control;
NTSTATUS EvtSercx2Control(
[in] WDFDEVICE Device,
[in] WDFREQUEST Request,
[in] size_t OutputBufferLength,
[in] size_t InputBufferLength,
[in] ULONG IoControlCode
)
{...}
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 serielle E/A-Steuerelementanforderung darstellt.
[in] OutputBufferLength
Die Länge des Ausgabepuffers für die serielle E/A-Steuerelementanforderung in Byte, die durch den Parameter Request angegeben wird.
[in] InputBufferLength
Die Länge des Eingabepuffers für die serielle E/A-Steuerelementanforderung, die durch den Parameter Request angegeben wird.
[in] IoControlCode
Gibt den I/O-Steuercode (IOCTL) aus der seriellen E/A-Steuerelementanforderung an, die durch den parameter Request angegeben wird. Die IOCTLs für serielle E/A-Steuerelementanforderungen werden in der Ntddser.h-Headerdatei definiert. Weitere Informationen finden Sie in den Hinweisen.
Rückgabewert
Die EvtSerCx2Control--Funktion gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Andernfalls wird ein entsprechender Fehlerstatuscode zurückgegeben.
Bemerkungen
Der serielle Controllertreiber muss diese Funktion implementieren. Der Treiber registriert die Funktion im Aufruf der SerCx2InitializeDevice Methode, die die Initialisierung des Framework-Geräteobjekts für den seriellen Controller beendet.
Mit der EvtSerCx2Control--Funktion kann der Treiber bestimmte serielle E/A-Steuerelementanforderungen verarbeiten, die SerCx2 nicht verarbeiten kann. SerCx2 verarbeitet alle Verarbeitungen für eine Teilmenge der seriellen IOCTLs, die in der Ntddser.h-Headerdatei definiert sind. SerCx2 basiert jedoch auf dem Treiber, um serielle E/A-Steuerungsanforderungen zu verarbeiten, um hardwareabhängige Vorgänge auszuführen.
Wenn SerCx2 eine serielle E/A-Steuerungsanforderung empfängt, die nur vom seriellen Controllertreiber verarbeitet werden kann, ruft SerCx2 die EvtSerCx2Control--Funktion auf, um die E/A-Steuerungsanforderung an den Treiber zu übergeben. Der Treiber ist für die Durchführung dieser Anforderung verantwortlich. Ein Treiber, der keine Unterstützung für eine bestimmte E/A-Steuerelementanforderung implementiert, sollte diese E/A-Steuerelementanforderung mit dem STATUS_NOT_SUPPORTED Fehlerstatuscode abschließen.
Um die E/A-Steuerelementanforderung abzuschließen, ruft der Treiber in der Regel die WdfRequestComplete Methode auf und stellt als Eingabeparameter den parameterwert Request Parameterwert und einen Statuswert auf, um anzugeben, ob die Anforderung erfolgreich war. Dieser Statuswert wird in den Statusblock der Anforderung geschrieben.
Der Rückgabewert der EvtSerCx2Control-Funktion sollte immer mit dem Statuswert übereinstimmen, den diese Funktion in den Statusblock der E/A-Steuerelementanforderung schreibt. Die aktuelle Implementierung von SerCx2 ignoriert diesen Rückgabewert.
SerCx2 ruft die EvtSerCx2Control--Funktion auf, um die in der folgenden Tabelle gezeigten IOCTLs zu verarbeiten. Die Spalte auf der rechten Seite der Tabelle gibt an, ob die EvtSerCx2Control Funktion erforderlich ist, um unterstützung für eine bestimmte IOCTL zu implementieren.
| Name der E/A-Steuerelementanforderung | Erforderlich oder optional |
|---|---|
| IOCTL_SERIAL_CLR_DTR | Wahlfrei |
| IOCTL_SERIAL_CLR_RTS | Erforderlich |
| IOCTL_SERIAL_GET_BAUD_RATE | Erforderlich |
| IOCTL_SERIAL_GET_COMMSTATUS | Erforderlich |
| IOCTL_SERIAL_GET_DTRRTS | Erforderlich |
| IOCTL_SERIAL_GET_HANDFLOW | Erforderlich |
| IOCTL_SERIAL_GET_LINE_CONTROL | Erforderlich |
| IOCTL_SERIAL_GET_MODEM_CONTROL | Erforderlich |
| IOCTL_SERIAL_GET_MODEMSTATUS | Erforderlich |
| IOCTL_SERIAL_GET_PROPERTIES | Erforderlich |
| IOCTL_SERIAL_SET_BAUD_RATE | Erforderlich |
| IOCTL_SERIAL_SET_BREAK_OFF | Erforderlich |
| IOCTL_SERIAL_SET_BREAK_ON | Erforderlich |
| IOCTL_SERIAL_SET_DTR | Wahlfrei |
| IOCTL_SERIAL_SET_FIFO_CONTROL | Wahlfrei |
| IOCTL_SERIAL_SET_HANDFLOW | Erforderlich |
| IOCTL_SERIAL_SET_LINE_CONTROL | Erforderlich |
| IOCTL_SERIAL_SET_MODEM_CONTROL | Erforderlich |
| IOCTL_SERIAL_SET_RTS | Erforderlich |
In der vorherigen Tabelle sind alle seriellen IOCTLs aufgeführt, die SerCx2 der EvtSerCx2Control--Funktion darstellt. Für alle IOCTL, die nicht in dieser Liste enthalten sind, verarbeitet SerCx2 entweder die IOCTL oder schlägt sofort das IOCTL fehl und legt den Anforderungsstatus auf STATUS_NOT_SUPPORTED fest. SerCx2 verarbeitet IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION Anforderungen, ruft jedoch die EvtSerCx2ApplyConfig Ereignisrückruffunktion während der Verarbeitung einer solchen Anforderung auf. SerCx2 verarbeitet IOCTL_SERIAL_PURGE Anforderungen, ruft jedoch möglicherweise die EvtSerCx2PurgeFifos Ereignisrückruffunktion während der Verarbeitung einer solchen Anforderung auf. SerCx führt die vorläufige Verarbeitung von IOCTL_SERIAL_SET_WAIT_MASK Anforderungen durch, ruft jedoch die EvtSerCx2SetWaitMask Ereignisrückruffunktion auf, wenn sie implementiert ist, um die Verarbeitung einer solchen Anforderung abzuschließen. Weitere Informationen zur SerCx2-Unterstützung für serielle IOCTLs finden Sie unter Serielle E/A-Anforderungsschnittstelle.
IOCTL_SERIAL_CLR_DTR und IOCTL_SERIAL_SET_DTR
Wenn die EvtSerCx2Control Funktion in Ihrem seriellen Controllertreiber die IOCTL_SERIAL_SET_DTR Anforderung unterstützt, sollte diese Funktion auch die IOCTL_SERIAL_CLR_DTR Anforderung unterstützen und umgekehrt. Wenn Ihr Treiber diese beiden Anforderungen nicht unterstützt, sollte der Handler des Treibers für die IOCTL_SERIAL_GET_DTRRTS-Anforderung das SERIAL_DTR_STATE Flagbit im Ausgabewert für diese Anforderung auf Null festlegen.
IOCTL_SERIAL_GET_DTRRTS
Die EvtSerCx2Control--Funktion in Ihrem seriellen Controllertreiber muss die IOCTL_SERIAL_GET_DTRRTS Anforderung unterstützen, der Treiberhandler für diese Anforderung ist jedoch erforderlich, um nur das SERIAL_RTS_STATE Flagbit im Ausgabewert für diese Anforderung zu unterstützen. Als Option kann der Treiber zusätzlich das SERIAL_DTR_STATE Flagbit unterstützen. Wenn das SERIAL_DTR_STATE Flagbit nicht unterstützt wird, legen Sie dieses Bit auf 0 fest.
IOCTL_SERIAL_GET_COMMSTATUS
Die EvtSerCx2Control--Funktion in Ihrem seriellen Controllertreiber muss die IOCTL_SERIAL_GET_COMMSTATUS Anforderung unterstützen, der Treiberhandler für diese Anforderung ist jedoch erforderlich, um nur die folgenden Member der SERIAL_STATUS Struktur zu unterstützen, die von dieser Anforderung verwendet wird:
- Fehler
- HoldReasons
IOCTL_SERIAL_GET_PROPERTIES
Die EvtSerCx2Control--Funktion in Ihrem seriellen Controllertreiber muss die IOCTL_SERIAL_GET_PROPERTIES Anforderung unterstützen. Der Handler des Treibers für diese Anforderung sollte den MaxBaud Member der von dieser Anforderung verwendeten SERIAL_COMMPROP Struktur auf die maximale unterstützte Baudrate (Bits pro Sekunde) festlegen. Wenn der serielle Controller beispielsweise eine maximale Baudrate von 115.200 bps unterstützt, legt der Treiber MaxBaud = 115200 fest.
IOCTL_SERIAL_GET_MODEMSTATUS
Die EvtSerCx2Control--Funktion in Ihrem seriellen Controllertreiber muss die IOCTL_SERIAL_GET_MODEMSTATUS Anforderung unterstützen. Der Handler des Treibers für diese Anforderung sollte den Ausgabewert der Anforderung auf den Unformatierten Modemstatusregisterwert festlegen, der von der seriellen Controllerhardware gelesen wird.
IOCTL_SERIAL_GET_HANDFLOW und IOCTL_SERIAL_SET_HANDFLOW
Die funktion EvtSerCx2Control in Ihrem seriellen Controllertreiber muss die IOCTL_SERIAL_GET_HANDFLOW und IOCTL_SERIAL_SET_HANDFLOW Anforderungen unterstützen, ist jedoch erforderlich, um nur eine Teilmenge der Flagbits zu unterstützen, die für diese Anforderungen definiert sind. Flagbits werden für die ControlHandShake und FlowReplace Member der SERIAL_HANDFLOW Struktur definiert, die von diesen Anforderungen verwendet wird.
Ihr Treiber muss das folgende Flagbit im ControlHandshake Mitglied unterstützen:
- SERIAL_CTS_HANDSHAKE
Ihr Treiber muss die folgenden Flagbits im FlowReplace- Mitglied unterstützen:
- SERIAL_RTS_CONTROL
- SERIAL_RTS_HANDSHAKE
Ein Treiber, der ein bestimmtes Flagbit im ControlHandShake- oder FlowReplace Member nicht unterstützt, sollte dieses Flag bit auf Null im Ausgabewert für die IOCTL_SERIAL_GET_HANDFLOW Anforderung festlegen. Wenn eine IOCTL_SERIAL_SET_HANDFLOW-Anforderung ein ControlHandshake- oder FlowReplace- Flagbit angibt, das der Treiber nicht unterstützt, sollte die EvtSerCx2Control-Funktion die Anforderung fehlschlagen und STATUS_INVALID_PARAMETER zurückgeben.
Als Option kann ein Treiber die XonLimit- und XoffLimit- Member der SERIAL_HANDFLOW Struktur unterstützen. Diese Mitglieder sind jedoch selten, wenn je, erforderlich, und Microsoft empfiehlt, sie zu unterstützen. Ein Treiber, der die XonLimit- nicht unterstützt, und XoffLimit- member sollten diese Member im Ausgabewert für die IOCTL_SERIAL_GET_HANDFLOW-Anforderung auf Null festlegen. Wenn eine IOCTL_SERIAL_SET_HANDFLOW Anforderung ein Nonzero-XonLimit- oder XoffLimit Member angibt und der Treiber diese Member nicht unterstützt, sollte die EvtSerCx2Control--Funktion die Anforderung nicht ausführen und STATUS_NOT_IMPLEMENTED zurückgeben.
Beispiele
Um eine EvtSerCx2Control- 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 EvtSerCx2Control Rückruffunktion zu definieren, die MyControlbenannt ist, verwenden Sie den EVT_SERCX2_CONTROL Funktionstyp, wie in diesem Codebeispiel gezeigt:
EVT_SERCX2_CONTROL MyControl;
Implementieren Sie dann die Rückruffunktion wie folgt:
_Use_decl_annotations_
NTSTATUS
MyControl(
WDFDEVICE Device,
WDFREQUEST Request,
size_t OutputBufferLength,
size_t InputBufferLength,
ULONG IoControlCode
)
{...}
Der EVT_SERCX2_CONTROL 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_CONTROL 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. |