EVT_SERCX2_SELECT_NEXT_RECEIVE_TRANSACTION_TYPE funzione di callback (sercx.h)

Articolo
02/29/2024

La funzione di callback dell'evento EvtSerCx2SelectNextReceiveTransactionType viene chiamata dalla versione 2 dell'estensione del framework seriale (SerCx2) per determinare quale meccanismo di trasferimento dati usare per l'operazione di lettura successiva.

Sintassi

EVT_SERCX2_SELECT_NEXT_RECEIVE_TRANSACTION_TYPE EvtSercx2SelectNextReceiveTransactionType;

SERCX2_TRANSACTION_TYPE EvtSercx2SelectNextReceiveTransactionType(
  [in]  WDFDEVICE Device,
  [in]  PMDL Mdl,
  [in]  ULONG Offset,
  [in]  ULONG RemainingLength,
  [out] SERCX2CUSTOMRECEIVE *CustomReceive,
  [out] PULONG NextTransactionLength
)
{...}

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] Mdl

Puntatore a un MDL che descrive le pagine di memoria estese dal buffer di lettura per la transazione di ricezione successiva. L'elenco di dispersione/raccolta per il trasferimento DMA userà l'area di questa memoria specificata dai parametri Offset e Length .

[in] Offset

Offset iniziale per il trasferimento dei dati successivo. Questo parametro è un offset di byte dall'inizio dell'area del buffer descritta da MDL. Se MDL specifica un totale di N byte di spazio buffer, i valori possibili di Offset si trovano nell'intervallo da 0 a N-1.

[in] RemainingLength

Numero totale di byte di dati che rimangono da trasferire nella richiesta di lettura corrente (IRP_MJ_READ). Se MDL specifica un totale di N byte di spazio buffer, i valori possibili di Lunghezza si trovano nell'intervallo da 1 a N-Offset.

[out] CustomReceive

Puntatore a un percorso in cui la funzione scrive l'handle di SERCX2CUSTOMRECEIVE nell'oggetto di ricezione personalizzato. Se la funzione restituisce SerCx2TransactionTypeCustom, la funzione deve fornire l'handle dell'oggetto creato in una chiamata precedente al metodo SerCx2CustomReceiveCreate . Se il valore restituito non è SerCx2TransactionTypeCustom, questo valore di output viene ignorato da SerCx2.

[out] NextTransactionLength

Puntatore a un percorso in cui la funzione scrive il numero di byte da trasferire nella transazione di ricezione successiva. Se il valore restituito è SerCx2TransactionTypeDefault, questo valore di output viene ignorato da SerCx2.

Valore restituito

La funzione EvtSerCx2SelectNextReceiveTransactionType restituisce una costante di enumerazione SERCX2_TRANSACTION_TYPE per indicare se utilizzare un tipo di transazione selezionato dal driver (I/O programmato), system DMA o trasferimento dati personalizzato o per consentire a SerCx2 di scegliere quale tipo di transazione utilizzare per la transazione di ricezione successiva.

Commenti

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

Se il driver del controller seriale non implementa una funzione EvtSerCx2SelectNextReceiveTransactionType , SerCx2 decide sempre il tipo di meccanismo di trasferimento dati (PIO, system DMA o personalizzato) da usare per la transazione di ricezione successiva. SerCx2 basa le sue decisioni sulle informazioni di configurazione di I/O fornite dal driver del controller seriale. Un driver che supporta le transazioni di ricezione DMA di sistema fornisce una struttura SERCX2_SYSTEM_DMA_RECEIVE_CONFIG che contiene queste informazioni. Un driver che supporta transazioni di ricezione personalizzate fornisce una struttura SERCX2_CUSTOM_RECEIVE_CONFIG che contiene queste informazioni.

Se il driver del controller seriale implementa una funzione EvtSerCx2SelectNextReceiveTransactionType , SerCx2 chiama questa funzione per determinare il tipo di meccanismo di trasferimento dati (PIO, system DMA o personalizzato) da usare per la transazione di ricezione successiva. È possibile implementare questa funzione se il controller seriale ha funzionalità hardware speciali che non possono essere descritte adeguatamente dalle informazioni di configurazione di I/O nelle strutture SERCX2_XXX_RECEIVE_CONFIG.

Nota Anche se un driver del controller seriale implementa una funzione EvtSerCx2SelectNextReceiveTransactionType , SerCx2 usa transazioni di ricezione PIO per eseguire determinati tipi di trasferimenti di dati senza prima chiamare questa funzione.

Per altre informazioni, vedere Panoramica delle transazioni di I/O SerCx2.

Esempio

Per definire una funzione di callback EvtSerCx2CustomReceiveSelectNextTransactionType , è 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 EvtSerCx2CustomReceiveSelectNextTransactionType denominataMyCustomReceiveSelectNextTransactionType, usare il tipo di funzione EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE , come illustrato in questo esempio di codice:

EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE  MyCustomReceiveTransactionStart;

Implementare quindi la funzione di callback come indicato di seguito:

_Use_decl_annotations_
SERCX2_TRANSACTION_TYPE
  EvtSerCx2SelectNextReceiveTransactionType(
    WDFDEVICE  Device,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  RemainingLength,
    SERCX2CUSTOMRECEIVE  *CustomReceive,
    PULONG  NextTransactionLength
    )
  {...}

Il tipo di funzione EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE è 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_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE 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.