EVT_SERCX2_CONTROL funzione di callback (sercx.h)

Articolo
10/30/2024

La EvtSerCx2Control funzione di callback degli eventi viene chiamata dalla versione 2 dell'estensione del framework seriale (SerCx2) per gestire una richiesta di controllo 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 nel relativo EvtDriverDeviceAdd funzione di callback. 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 I/O seriale specificata dal parametro Request .

[in] InputBufferLength

Lunghezza, in byte, del buffer di input per la richiesta di controllo di 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. Gli IOCTLs per le richieste di controllo I/O seriali vengono definiti nel file di intestazione Ntddser.h. Per altre informazioni, vedere 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.

Osservazioni

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 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 I/O seriale che può essere gestita solo dal driver del controller seriale, SerCx2 chiama la funzione EvtSerCx2Control per distribuire la richiesta di controllo I/O al driver. Il driver è responsabile del completamento di questa 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 I/O, il driver chiama in genere il metodo WdfRequestComplete e fornisce, come parametri di input, il valore del parametro richiesta 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 che questa funzione scrive 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 particolare IOCTL.

Nome della richiesta di controllo I/O	Obbligatorio o facoltativo
IOCTL_SERIAL_CLR_DTR	Opzionale
IOCTL_SERIAL_CLR_RTS	Obbligatorio
IOCTL_SERIAL_GET_BAUD_RATE	Obbligatorio
IOCTL_SERIAL_GET_COMMSTATUS	Obbligatorio
IOCTL_SERIAL_GET_DTRRTS	Obbligatorio
IOCTL_SERIAL_GET_HANDFLOW	Obbligatorio
IOCTL_SERIAL_GET_LINE_CONTROL	Obbligatorio
IOCTL_SERIAL_GET_MODEM_CONTROL	Obbligatorio
IOCTL_SERIAL_GET_MODEMSTATUS	Obbligatorio
IOCTL_SERIAL_GET_PROPERTIES	Obbligatorio
IOCTL_SERIAL_SET_BAUD_RATE	Obbligatorio
IOCTL_SERIAL_SET_BREAK_OFF	Obbligatorio
IOCTL_SERIAL_SET_BREAK_ON	Obbligatorio
IOCTL_SERIAL_SET_DTR	Opzionale
IOCTL_SERIAL_SET_FIFO_CONTROL	Opzionale
IOCTL_SERIAL_SET_HANDFLOW	Obbligatorio
IOCTL_SERIAL_SET_LINE_CONTROL	Obbligatorio
IOCTL_SERIAL_SET_MODEM_CONTROL	Obbligatorio
IOCTL_SERIAL_SET_RTS	Obbligatorio

Nella tabella precedente sono elencati tutti i IOCTLs seriali che SerCx2 presenta alla funzione EvtSerCx2Control . Per qualsiasi IOCTL non presente in questo elenco, SerCx2 gestisce l'IOCTL o non riesce immediatamente il IOCTL e imposta lo stato della richiesta su STATUS_NOT_SUPPORTED. SerCx2 gestisce IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION richieste, ma chiama la EvtSerCx2ApplyConfig funzione di callback degli eventi 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 il EvtSerCx2SetWaitMask funzione di callback degli eventi, se implementata, per completare la gestione di tale richiesta. Per altre informazioni sul supporto serCx2 per IOCTLs seriali, vedere 'interfaccia di 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

Come opzione, il driver può supportare anche qualsiasi altro membro di questa struttura. Impostare tutti i membri non supportati su zero.

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 MaxBaud della struttura SERIAL_COMMPROP utilizzata da questa richiesta alla velocità baud massima supportata, espressa in bit al secondo (bps). Ad esempio, se il controller seriale supporta una velocità massima di 115.200 bps, il driver imposta MaxBaud = 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 ControlHandShake e FlowReplace membri della struttura SERIAL_HANDFLOW utilizzata da queste richieste.

Il driver deve supportare il bit del flag seguente nel membro ControlHandshake :

SERIAL_CTS_HANDSHAKE

Come opzione, un driver può supportare qualsiasi altro bit di flag definito per il membro ControlHandshake.

Il driver deve supportare i bit di flag seguenti nel membro FlowReplace :

SERIAL_RTS_CONTROL
SERIAL_RTS_HANDSHAKE

Come opzione, un driver può supportare qualsiasi altro bit di flag definito per il membro FlowReplace . Tuttavia, questi altri bit di flag sono raramente, se mai, necessari e Microsoft consiglia di supportarli.

Un driver che non supporta un bit di flag specifico nel ControlHandShake o membro FlowReplace deve impostare questo bit flag su zero nel valore di output per la richiesta di IOCTL_SERIAL_GET_HANDFLOW. Se una richiesta di IOCTL_SERIAL_SET_HANDFLOW specifica un ControlHandshake o bit di flag FlowReplace che il driver non supporta, la funzione EvtSerCx2Control deve non riuscire la richiesta e restituire STATUS_INVALID_PARAMETER.

Come opzione, un driver può supportare il XonLimit e XoffLimit membri della struttura di SERIAL_HANDFLOW. Tuttavia, questi membri sono raramente, se mai, necessari e Microsoft consiglia di non supportarli. Un driver che non supporta il XonLimit e membri XoffLimit devono 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 XonLimit o membro di XoffLimit e il driver non supporta questi membri, la funzione EvtSerCx2Control deve non riuscire la richiesta e restituire STATUS_NOT_IMPLEMENTED.

Esempi

Per definire un EvtSerCx2Control funzione di callback, è prima necessario 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 usando i tipi di funzione di callback consente di l'analisi del codice per i driver, del driver statico (SDV) e altri strumenti di verifica rilevano errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire un EvtSerCx2Control funzione di callback denominata MyControl, usare il tipo di funzione EVT_SERCX2_CONTROL, come illustrato in questo esempio di codice:

EVT_SERCX2_CONTROL  MyControl;

Implementare quindi la funzione di callback come segue:

_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 i tipi di ruolo della funzione per i driver KMDF. Per altre informazioni su Use_decl_annotations, vedere l'annotazione del comportamento della funzione.

Fabbisogno

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.