FILTER_PAUSE funzione di callback (ndis.h)

Articolo
08/07/2023

NDIS chiama la funzione FilterPause di un driver di filtro per avviare un'operazione di sospensione per il modulo di filtro specificato.

Nota È necessario dichiarare la funzione usando il tipo di FILTER_PAUSE . Per altre informazioni, vedere la sezione Esempi seguente.

Sintassi

FILTER_PAUSE FilterPause;

NDIS_STATUS FilterPause(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_FILTER_PAUSE_PARAMETERS PauseParameters
)
{...}

Parametri

[in] FilterModuleContext

Handle per l'area di contesto per il modulo di filtro che il driver di filtro deve sospendere. Il driver di filtro ha creato e inizializzato questa area di contesto nella funzione FilterAttach .

[in] PauseParameters

Puntatore a un oggetto NDIS_FILTER_PAUSE_PARAMETERS struttura che definisce i parametri di sospensione per il modulo di filtro.

Valore restituito

I driver NDIS non possono avere esito negativo per una richiesta di sospensione. Il driver di filtro deve chiamare la funzione NdisWriteEventLogEntry insieme ai parametri che specificano il motivo di eventuali errori che si verificano.

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	FilterPause ha sospeso correttamente il modulo di filtro specificato.
NDIS_STATUS_PENDING	Il driver di filtro completerà la richiesta in modo asincrono con una chiamata alla funzione NdisFPauseComplete .

Commenti

FilterPause è una funzione obbligatoria. NDIS può chiamare FilterPause quando il modulo di filtro si trova nello stato In esecuzione . Il modulo di filtro passa allo stato Sospensione all'inizio dell'esecuzione nella funzione FilterPause .

Un driver di filtro esegue le operazioni seguenti quando NDIS chiama FilterPause:

Deve chiamare il Funzione NdisFSendNetBufferListsComplete per qualsiasi buffer di invio in coda creato da un driver eccessivamente in esecuzione.
Deve chiamare il Funzione NdisFReturnNetBufferLists per qualsiasi buffer di ricezione in coda creato da un driver sottostante.
Deve attendere che NDIS restituisca tutte le richieste di invio in sospeso che il driver ha avuto origine nel Funzione FilterSendNetBufferListsComplete .
Deve attendere che NDIS restituisca tutte le indicazioni di ricezione in sospeso che il driver ha avuto origine nel Funzione FilterReturnNetBufferLists .

Dopo che il driver di filtro restituisce NDIS_STATUS_SUCCESS da FilterPause o chiama la funzione NdisFPauseComplete , l'operazione di sospensione è stata completata. Il modulo di filtro si trova nello stato Sospeso .

Negli stati Sospensione o Sospensione , un driver di filtro deve continuare a gestire le richieste OID o le indicazioni di stato. Il driver deve rifiutare le chiamate al relativo Funzione FilterSendNetBufferLists . Il driver può passare le chiamate al suo Funzione FilterReceiveNetBufferLists . Tuttavia, il driver non può passare alcun buffer creato. Il driver non deve avere origine alcuna indicazione o inviare richieste.

Nello stato Sospeso il modulo di filtro non deve generare richieste di invio o ricevere indicazioni.

NDIS chiama la funzione FilterRestart per avviare una richiesta di riavvio per un modulo di filtro nello stato Sospeso .

NDIS chiama FilterPause in IRQL = PASSIVE_LEVEL.

Esempi

Per definire una funzione FilterPause , è innanzitutto necessario fornire una dichiarazione di funzione che identifica il tipo di funzione che si sta definendo. Windows fornisce un set di tipi di funzione per i driver. La dichiarazione di una funzione con i tipi di funzione consente di eseguire l'analisi del codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica rilevano gli errori ed è un requisito per la scrittura dei driver per il sistema operativo Windows.

Ad esempio, per definire una funzione FilterPause denominata "MyPause", usare il tipo FILTER_PAUSE , come illustrato in questo esempio di codice:

FILTER_PAUSE MyPause;

Implementare quindi la funzione come segue:

_Use_decl_annotations_
NDIS_STATUS
 MyPause(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_FILTER_PAUSE_PARAMETERS  FilterPauseParameters
    )
  {...}

Il tipo di funzione FILTER_PAUSE è definito nel file di intestazione Ndis.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 garantisce che vengano utilizzate le annotazioni applicate al tipo di funzione FILTER_PAUSE 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 NDIS.

Per informazioni sulle Use_decl_annotations, vedere Annotazione del comportamento della funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Supportato in NDIS 6.0 e versioni successive.
Piattaforma di destinazione	Windows
Intestazione	ndis.h (include Ndis.h)
IRQL	PASSIVE_LEVEL