EVT_SERCX2_CONTROL funzione di callback (sercx.h)
La funzione di callback degli eventi EvtSerCx2Control viene chiamata dalla versione 2 dell'estensione del framework seriale (SerCx2) per gestire una richiesta di controllo di I/O seriale.
Sintassi
EVT_SERCX2_CONTROL EvtSercx2Control;
NTSTATUS EvtSercx2Control(
[in] WDFDEVICE Device,
[in] WDFREQUEST Request,
[in] size_t OutputBufferLength,
[in] size_t InputBufferLength,
[in] ULONG IoControlCode
)
{...}
Parametri
[in] Device
Handle WDFDEVICE per l'oggetto dispositivo framework che rappresenta il controller seriale. Il driver del controller seriale ha creato questo oggetto nella relativa funzione di callback EvtDriverDeviceAdd . Per altre informazioni, vedere SerCx2InitializeDevice.
[in] Request
Handle WDFREQUEST per l'oggetto richiesta framework che rappresenta la richiesta di controllo I/O seriale.
[in] OutputBufferLength
Lunghezza, in byte, del buffer di output per la richiesta di controllo di I/O seriale specificata dal parametro Request .
[in] InputBufferLength
Lunghezza, in byte, del buffer di input per la richiesta di controllo I/O seriale specificata dal parametro Request .
[in] IoControlCode
Specifica il codice di controllo I/O (IOCTL) dalla richiesta di controllo I/O seriale specificata dal parametro Request . IOCTLs per le richieste di controllo I/O seriali sono definiti nel file di intestazione Ntddser.h. Per altre informazioni, vedere la sezione Osservazioni.
Valore restituito
La funzione EvtSerCx2Control restituisce STATUS_SUCCESS se la chiamata ha esito positivo. In caso contrario, restituisce un codice di stato di errore appropriato.
Commenti
Il driver del controller seriale deve implementare questa funzione. Il driver registra la funzione nella chiamata al metodo SerCx2InitializeDevice che completa l'inizializzazione dell'oggetto dispositivo framework per il controller seriale.
La funzione EvtSerCx2Control consente al driver di gestire determinate richieste di controllo di I/O seriali che SerCx2 non possono gestire. SerCx2 gestisce tutte le elaborazioni per un subset dei valori IOCTL seriali definiti nel file di intestazione Ntddser.h. Tuttavia, SerCx2 si basa sul driver per gestire le richieste di controllo di I/O seriali per eseguire operazioni dipendenti dall'hardware.
Quando SerCx2 riceve una richiesta di controllo di I/O seriale che può essere gestita solo dal driver del controller seriale, SerCx2 chiama la funzione EvtSerCx2Control per consegnare la richiesta di controllo I/O al driver. Il driver è responsabile del completamento della richiesta. Un driver che non implementa il supporto per una determinata richiesta di controllo di I/O deve completare questa richiesta di controllo di I/O con il codice di stato di errore STATUS_NOT_SUPPORTED.
Per completare la richiesta di controllo di I/O, il driver chiama in genere il metodo WdfRequestComplete e fornisce, come parametri di input, il valore del parametro Request e un valore di stato per indicare se la richiesta ha avuto esito positivo. Questo valore di stato viene scritto nel blocco di stato della richiesta.
Il valore restituito della funzione EvtSerCx2Control deve corrispondere sempre al valore di stato scritto da questa funzione nel blocco di stato della richiesta di controllo I/O. L'implementazione corrente di SerCx2 ignora questo valore restituito.
SerCx2 chiama la funzione EvtSerCx2Control per gestire i valori IOCTLs illustrati nella tabella seguente. La colonna sul lato destro della tabella indica se la funzione EvtSerCx2Control è necessaria per implementare il supporto per un determinato IOCTL.
| Nome della richiesta di controllo di I/O | Obbligatoria o facoltativa |
|---|---|
| IOCTL_SERIAL_CLR_DTR | Facoltativo |
| IOCTL_SERIAL_CLR_RTS | Necessario |
| IOCTL_SERIAL_GET_BAUD_RATE | Necessario |
| IOCTL_SERIAL_GET_COMMSTATUS | Necessario |
| IOCTL_SERIAL_GET_DTRRTS | Necessario |
| IOCTL_SERIAL_GET_HANDFLOW | Necessario |
| IOCTL_SERIAL_GET_LINE_CONTROL | Necessario |
| IOCTL_SERIAL_GET_MODEM_CONTROL | Necessario |
| IOCTL_SERIAL_GET_MODEMSTATUS | Necessario |
| IOCTL_SERIAL_GET_PROPERTIES | Necessario |
| IOCTL_SERIAL_SET_BAUD_RATE | Necessario |
| IOCTL_SERIAL_SET_BREAK_OFF | Necessario |
| IOCTL_SERIAL_SET_BREAK_ON | Necessario |
| IOCTL_SERIAL_SET_DTR | Facoltativo |
| IOCTL_SERIAL_SET_FIFO_CONTROL | Facoltativo |
| IOCTL_SERIAL_SET_HANDFLOW | Necessario |
| IOCTL_SERIAL_SET_LINE_CONTROL | Necessario |
| IOCTL_SERIAL_SET_MODEM_CONTROL | Necessario |
| IOCTL_SERIAL_SET_RTS | Necessario |
Nella tabella precedente sono elencati tutti i IOCTL seriali presentati da SerCx2 alla funzione EvtSerCx2Control . Per qualsiasi IOCTL non incluso nell'elenco, SerCx2 gestisce l'IOCTL o genera immediatamente un errore in IOCTL e imposta lo stato della richiesta su STATUS_NOT_SUPPORTED. SerCx2 gestisce IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION richieste, ma chiama la funzione di callback dell'evento EvtSerCx2ApplyConfig durante l'elaborazione di tale richiesta. SerCx2 gestisce IOCTL_SERIAL_PURGE richieste, ma potrebbe chiamare la funzione di callback dell'evento EvtSerCx2PurgeFifos durante l'elaborazione di tale richiesta. SerCx esegue l'elaborazione preliminare delle richieste di IOCTL_SERIAL_SET_WAIT_MASK , ma chiama la funzione di callback dell'evento EvtSerCx2SetWaitMask , se implementata, per completare la gestione di tale richiesta. Per altre informazioni sul supporto serCx2 per IOCTL seriali, vedere Interfaccia richiesta I/O seriale.
IOCTL_SERIAL_CLR_DTR e IOCTL_SERIAL_SET_DTR
Se la funzione EvtSerCx2Control nel driver del controller seriale supporta la richiesta di IOCTL_SERIAL_SET_DTR , questa funzione deve supportare anche la richiesta di IOCTL_SERIAL_CLR_DTR e viceversa. Se il driver non supporta queste due richieste, il gestore del driver per la richiesta di IOCTL_SERIAL_GET_DTRRTS deve impostare il bit del flag SERIAL_DTR_STATE nel valore di output per questa richiesta su zero.
IOCTL_SERIAL_GET_DTRRTS
La funzione EvtSerCx2Control nel driver del controller seriale deve supportare la richiesta di IOCTL_SERIAL_GET_DTRRTS , ma il gestore del driver per questa richiesta è necessario per supportare solo il bit del flag SERIAL_RTS_STATE nel valore di output per questa richiesta. Come opzione, il driver può supportare anche il bit del flag SERIAL_DTR_STATE. Se il bit del flag SERIAL_DTR_STATE non è supportato, impostare questo bit su zero.
IOCTL_SERIAL_GET_COMMSTATUS
La funzione EvtSerCx2Control nel driver del controller seriale deve supportare la richiesta di IOCTL_SERIAL_GET_COMMSTATUS , ma il gestore del driver per questa richiesta è necessario per supportare solo i membri seguenti della struttura SERIAL_STATUS utilizzata da questa richiesta:
- Errori
- HoldReasons
IOCTL_SERIAL_GET_PROPERTIES
La funzione EvtSerCx2Control nel driver del controller seriale deve supportare la richiesta di IOCTL_SERIAL_GET_PROPERTIES . Il gestore del driver per questa richiesta deve impostare il membro MaxSoluted della struttura SERIAL_COMMPROP utilizzata da questa richiesta sulla velocità massima di baud supportata, espressa in bit al secondo (bps). Ad esempio, se il controller seriale supporta una velocità massima di 115.200 bps, il driver imposta MaxSoluted = 115200.
IOCTL_SERIAL_GET_MODEMSTATUS
La funzione EvtSerCx2Control nel driver del controller seriale deve supportare la richiesta di IOCTL_SERIAL_GET_MODEMSTATUS . Il gestore del driver per questa richiesta deve impostare il valore di output della richiesta sul valore del registro di stato del modem non elaborato letto dall'hardware del controller seriale.
IOCTL_SERIAL_GET_HANDFLOW e IOCTL_SERIAL_SET_HANDFLOW
La funzione EvtSerCx2Control nel driver del controller seriale deve supportare le richieste di IOCTL_SERIAL_GET_HANDFLOW e IOCTL_SERIAL_SET_HANDFLOW , ma è necessario per supportare solo un subset dei bit di flag definiti per queste richieste. I bit di flag sono definiti per i membri ControlHandShake e FlowReplace della struttura SERIAL_HANDFLOW utilizzata da queste richieste.
Il driver deve supportare il flag seguente nel membro ControlHandshake :
- SERIAL_CTS_HANDSHAKE
Il driver deve supportare i bit di flag seguenti nel membro FlowReplace :
- SERIAL_RTS_CONTROL
- SERIAL_RTS_HANDSHAKE
Un driver che non supporta un bit di flag specifico nel membro ControlHandShake o FlowReplace deve impostare questo flag bit su zero nel valore di output per la richiesta di IOCTL_SERIAL_GET_HANDFLOW . Se una richiesta di IOCTL_SERIAL_SET_HANDFLOW specifica un bit di flag ControlHandshake o FlowReplace che il driver non supporta, la funzione EvtSerCx2Control non deve eseguire la richiesta e restituire STATUS_INVALID_PARAMETER.
Come opzione, un driver può supportare i membri XonLimit e XoffLimit della struttura SERIAL_HANDFLOW . Tuttavia, questi membri sono raramente, se mai, necessari e Microsoft consiglia di non supportarli. Un driver che non supporta i membri XonLimit e XoffLimit deve impostare questi membri su zero nel valore di output per la richiesta di IOCTL_SERIAL_GET_HANDFLOW . Se una richiesta di IOCTL_SERIAL_SET_HANDFLOW specifica un membro XonLimit o XoffLimit diverso da zero e il driver non supporta questi membri, la funzione EvtSerCx2Control non riesce la richiesta e restituisce STATUS_NOT_IMPLEMENTED.
Esempio
Per definire una funzione di callback EvtSerCx2Control , è necessario innanzitutto fornire una dichiarazione di funzione che identifica il tipo di funzione di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione tramite i tipi di funzione di callback consente di analizzare il codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica di trovare errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.
Ad esempio, per definire una funzione di callback EvtSerCx2Control denominata MyControl, usare il tipo di funzione EVT_SERCX2_CONTROL , come illustrato nell'esempio di codice seguente:
EVT_SERCX2_CONTROL MyControl;
Implementare quindi la funzione di callback come indicato di seguito:
_Use_decl_annotations_
NTSTATUS
MyControl(
WDFDEVICE Device,
WDFREQUEST Request,
size_t OutputBufferLength,
size_t InputBufferLength,
ULONG IoControlCode
)
{...}
Il tipo di funzione EVT_SERCX2_CONTROL è definito nel file di intestazione Sercx.h. Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations assicura che vengano utilizzate le annotazioni applicate al tipo di funzione EVT_SERCX2_CONTROL nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo di funzione per i driver KMDF. Per altre informazioni sulle Use_decl_annotations, vedere Annotazione del comportamento della funzione.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Disponibile a partire da Windows 8.1. |
| Piattaforma di destinazione | Desktop |
| Intestazione | sercx.h |
| IRQL | Chiamato in IRQL <= DISPATCH_LEVEL. |
Vedi anche
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per