EVT_SERCX2_SET_WAIT_MASK funzione di callback (sercx.h)

Articolo
10/30/2024

La EvtSerCx2SetWaitMask funzione di callback degli eventi 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 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 IOCTL_SERIAL_SET_WAIT_MASK.

[in] WaitMask

Nuova maschera di attesa. Per altre informazioni, vedere 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 è diversa da 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 un precedente EvtSerCx2SetWaitMask chiamata. Se la nuova maschera di attesa è zero, il driver rimuove semplicemente la maschera di attesa precedente e smette di monitorare eventuali eventi 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 di IOCTL_SERIAL_SET_WAIT_MASK con codice di stato di errore STATUS_NOT_SUPPORTED.

Per monitorare gli eventi nella maschera di attesa, la funzione EvtSerCx2SetWaitMask in genere abilita gli interrupt per questi eventi. Successivamente, quando viene rilevato un evento nella maschera di attesa, il driver del controller seriale chiama il metodo SerCx2CompleteWait per notificare a SerCx2 dell'evento.

La funzione EvtSerCx2SetWaitMask è responsabile del completamento della richiesta di IOCTL_SERIAL_SET_WAIT_MASK a cui punta il parametro request . Dopo che il driver del controller seriale abilita gli interrupt necessari, chiama 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.

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 del primo EvtSerCx2SetWaitMask chiamata, la maschera di attesa è effettivamente zero e il driver del controller seriale non monitora alcun evento SERIAL_EV_XXX.

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

SERIAL_EV_PERR
SERIAL_EV_RING
SERIAL_EV_RXFLAG

Pertanto, la maschera di attesa fornita al EvtSerCx2SetWaitMask funzione 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 set di dati pronta (DSR), la funzione EvtSerCx2SetWaitMask deve supportare SERIAL_EV_DSR. Come opzione, un driver può supportare qualsiasi altro flag di evento descritto 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.

Esempi

Per definire un EvtSerCx2SetWaitMask 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 EvtSerCx2SetWaitMask funzione di callback denominata MySetWaitmask, usare il tipo di funzione EVT_SERCX2_SET_WAIT_MASK, come illustrato in questo esempio di codice:

EVT_SERCX2_SET_WAIT_MASK  MySetWaitmask;

Implementare quindi la funzione di callback come segue:

_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 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_SET_WAIT_MASK 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.