FILTER_RESTART funzione di callback (ndis.h)

Articolo
08/07/2023

La funzione FilterRestart avvia un'operazione di riavvio per il modulo di filtro specificato.

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

Sintassi

FILTER_RESTART FilterRestart;

NDIS_STATUS FilterRestart(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_FILTER_RESTART_PARAMETERS RestartParameters
)
{...}

Parametri

[in] FilterModuleContext

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

[in] RestartParameters

Puntatore a un oggetto NDIS_FILTER_RESTART_PARAMETERS struttura che definisce i parametri di riavvio per il modulo di filtro.

Valore restituito

FilterRestart restituisce uno dei valori di stato seguenti:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	FilterRestart ha riavviato correttamente il modulo di filtro specificato.
NDIS_STATUS_PENDING	Il driver di filtro completerà la richiesta in modo asincrono con una chiamata alla funzione NdisFRestartComplete dopo aver completato l'operazione di riavvio.
NDIS_STATUS_RESOURCES	FilterRestart non è riuscito a causa di risorse insufficienti.
NDIS_STATUS_FAILURE	Nessuno dei valori di stato precedenti si applica. Il driver di filtro deve chiamare la funzione NdisWriteEventLogEntry insieme ai parametri che specificano il motivo dell'errore.

Commenti

FilterRestart è una funzione obbligatoria per i driver di filtro. NDIS può chiamare FilterRestart quando un modulo di filtro si trova nello stato Sospeso . Il modulo di filtro entra nello stato Riavvio all'inizio dell'esecuzione di FilterRestart.

Quando NDIS chiama FilterRestart, un driver di filtro:

Deve completare le operazioni necessarie per riavviare le normali operazioni di invio e ricezione.
Facoltativamente legge o scrive parametri di configurazione.
Facoltativamente, rialloca i pool di buffer.
Facoltativamente, modifica gli attributi di riavvio specificati nel membro RestartAttributes del NDIS_FILTER_RESTART_PARAMETERS struttura. Se il puntatore in RestartAttributes è NULL, il driver di filtro non deve modificare o aggiungere all'elenco degli attributi di riavvio. Se il puntatore in RestartAttributes è diverso da NULL, punta alla prima struttura NDIS_RESTART_ATTRIBUTES nell'elenco degli attributi di riavvio. Se un driver di filtro non viene riavviato, non deve modificare alcun attributo.
Facoltativamente, usa le richieste OID per eseguire query o impostare informazioni nei driver sottostanti. I driver di filtro non devono inviare richieste OID per informazioni già fornite nell'elenco degli attributi di riavvio.
Restituisce NDIS_STATUS_SUCCESS o uno stato di errore.

Se un driver di filtro modifica l'elenco degli attributi di riavvio, il driver di filtro:

Non deve modificare attributi specifici del supporto se non riconosce l'OID nel membro Oid del NDIS_RESTART_ATTRIBUTES struttura.
Può aggiungere nuovi attributi specifici del supporto all'elenco degli attributi di riavvio. In questo caso, il driver di filtro deve allocare un nuovo NDIS_RESTART_ATTRIBUTES struttura, ad esempio con Funzione NdisAllocateMemoryWithTagPriority e fornire spazio di memoria per i nuovi attributi. Dopo aver propagato gli attributi di riavvio ai driver overlying, NDIS libera la memoria degli attributi per i driver di filtro.
Può modificare gli attributi specifici del supporto nell'elenco degli attributi di riavvio. Se il driver di filtro richiede più spazio di memoria, può liberare la struttura NDIS_RESTART_ATTRIBUTES con la funzione NdisFreeMemory e allocare una nuova struttura per contenere le informazioni modificate. Dopo aver propagato gli attributi di riavvio ai driver overlying, NDIS libera la memoria degli attributi per i driver di filtro.
Se il membro Oid nella struttura NDIS_RESTART_ATTRIBUTES è OID_GEN_MINIPORT_RESTART_ATTRIBUTES, assicurarsi che NDIS_RESTART_GENERAL_ATTRIBUTES struttura contiene le informazioni richieste dal driver di filtro. Per assicurarsi che la struttura NDIS_RESTART_GENERAL_ATTRIBUTES contenga le informazioni necessarie, è necessario controllare il membro Revision nella struttura NDIS_OBJECT_HEADER specificata nel membro Header della struttura NDIS_RESTART_GENERAL_ATTRIBUTES.
Nota Un driver di filtro può modificare qualsiasi membro nella struttura NDIS_RESTART_GENERAL_ATTRIBUTES. Se alcuni attributi che il driver di filtro deve modificare non sono inclusi nella revisione della struttura fornita da NDIS, il driver di filtro deve basarsi su driver eccessivamente in grado di inviare richieste OID per gli attributi mancanti. Il driver di filtro può modificare gli attributi quando completa la richiesta OID.
Se il driver di filtro modifica gli attributi di riavvio, specificare una funzione FilterOidRequest . Il driver di filtro deve assicurarsi che le informazioni che i driver overlying ricevono negli attributi di riavvio siano coerenti con le informazioni ricevute in risposta alle richieste OID.

Dopo che il driver di filtro restituisce lo stato o chiama la funzione NdisFRestartComplete , l'operazione di riavvio è stata completata. Se l'operazione è stata completata correttamente, il modulo di filtro si trova nello stato In esecuzione e viene ripresa l'elaborazione normale di invio e ricezione. Se l'operazione di riavvio non è riuscita, il modulo di filtro torna allo stato Sospeso .

NDIS chiama FilterRestart in IRQL = PASSIVE_LEVEL.

Esempi

Per definire una funzione FilterRestart , è 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 FilterRestart denominata "MyRestart ", usare il tipo FILTER_RESTART come illustrato nell'esempio di codice seguente:

FILTER_RESTART MyRestart;

Implementare quindi la funzione come segue:

_Use_decl_annotations_
NDIS_STATUS
 MyRestart(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_FILTER_RESTART_PARAMETERS  FilterRestartParameters
    )
  {...}

Il tipo di funzione FILTER_RESTART è 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_RESTART 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