EVT_SERCX2_SET_WAIT_MASK funzione di callback (sercx.h)

Articolo
08/07/2023

La funzione di callback dell'evento EvtSerCx2SetWaitMask viene chiamata dalla versione 2 dell'estensione del framework seriale (SerCx2) per configurare il controller seriale per monitorare un set di eventi hardware specificati da una maschera di attesa.

Sintassi

EVT_SERCX2_SET_WAIT_MASK EvtSercx2SetWaitMask;

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

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 EvtDriverDeviceAdd callback. Per altre informazioni, vedere SerCx2InitializeDevice.

[in] Request

Handle WDFREQUEST per l'oggetto richiesta framework che rappresenta la richiesta di IOCTL_SERIAL_SET_WAIT_MASK .

[in] WaitMask

Nuova maschera di attesa. Per altre informazioni, vedere la sezione Osservazioni.

Valore restituito

nessuno

Osservazioni

Il driver del controller seriale può, come opzione, implementare questa funzione. Se implementato, il driver registra la funzione nella chiamata al metodo SerCx2InitializeDevice che completa l'inizializzazione dell'oggetto dispositivo framework per il controller seriale.

Quando SerCx riceve una richiesta di IOCTL_SERIAL_SET_WAIT_MASK da un client, il gestore della richiesta in SerCx2 chiama la funzione EvtSerCx2SetWaitMask , se implementata, per notificare al driver che la maschera di attesa è stata modificata. Se la maschera di attesa non è zero, il driver inizia immediatamente a monitorare gli eventi nella nuova maschera di attesa e rimuove qualsiasi maschera di attesa precedente che potrebbe essere stata fornita in una precedente chiamata EvtSerCx2SetWaitMask . Se la nuova maschera di attesa è zero, il driver rimuove semplicemente la maschera di attesa precedente e smette di monitorare eventuali eventi di maschera di attesa. Per altre informazioni sui tipi di eventi che possono essere specificati da una maschera di attesa, vedere SERIAL_EV_XXX.

Se il driver non implementa questa funzione, SerCx2 non riesce tutte le richieste IOCTL_SERIAL_SET_WAIT_MASK con codice di stato degli errori STATUS_NOT_SUPPORTED.

Per monitorare gli eventi nella maschera di attesa, la funzione EvtSerCx2SetWaitMask in genere abilita gli interruzioni per questi eventi. In seguito, quando viene rilevato un evento nella maschera di attesa, il driver del controller seriale chiama il metodo SerCx2CompleteWait per inviare una notifica a SerCx2 dell'evento.

La funzione EvtSerCx2SetWaitMask è responsabile del completamento della richiesta IOCTL_SERIAL_SET_WAIT_MASK puntata dal parametro Request . Dopo che il driver del controller seriale abilita gli interruzioni necessari, chiama 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.

Prima che il driver del controller seriale chiami WdfRequestComplete per completare la richiesta, il driver deve completare tutte le chiamate a SerCx2CompleteWait che potrebbero essere ancora in sospeso a causa di eventi nella maschera di attesa precedente.

Inizialmente, dopo che un client apre una connessione logica alla porta seriale e prima della prima chiamata EvtSerCx2SetWaitMask , la maschera di attesa è effettivamente zero e il driver del controller seriale non monitora gli eventi SERIAL_EV_XXX .

SerCx2 non riesce una richiesta di IOCTL_SERIAL_SET_WAIT_MASK che include una maschera di attesa che include uno dei flag di evento seguenti SERIAL_EV_XXX:

SERIAL_EV_PERR
SERIAL_EV_RING
SERIAL_EV_RXFLAG

Pertanto, la maschera di attesa fornita alla funzione EvtSerCx2SetWaitMask non contiene mai alcun flag di evento nell'elenco precedente.

Se implementato, la funzione EvtSerCx2SetWaitMask deve supportare i flag di evento seguenti:

SERIAL_EV_CTS
SERIAL_EV_BREAK
SERIAL_EV_ERR

Inoltre, se il controller seriale ha una linea di segnale pronta per il set di dati (DSR), la funzione EvtSerCx2SetWaitMask deve supportare SERIAL_EV_DSR. Come opzione, un driver può supportare uno qualsiasi degli altri flag di eventi descritti in SERIAL_EV_XXX. Se la maschera di attesa specifica un evento che il driver non supporta, la funzione EvtSerCx2SetWaitMask deve non riuscire la richiesta e impostare il valore di stato nella richiesta su STATUS_INVALID_PARAMETER.

Esempio

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

Ad esempio, per definire una funzione di callback EvtSerCx2SetWaitMask denominata MySetWaitmask, usare il tipo di funzione EVT_SERCX2_SET_WAIT_MASK , come illustrato nell'esempio di codice seguente:

EVT_SERCX2_SET_WAIT_MASK  MySetWaitmask;

Implementare quindi la funzione di callback come indicato di seguito:

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

Il tipo di funzione EVT_SERCX2_SET_WAIT_MASK è definito nel file di intestazione Sercx.h. Per identificare in modo più accurato gli errori durante l'esecuzione degli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations garantisce che vengano usate le annotazioni applicate al tipo di funzione EVT_SERCX2_SET_WAIT_MASK nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo per i driver KMDF. Per altre informazioni su 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.