FILTER_ATTACH funzione di callback (ndis.h)

Articolo
08/07/2023

NDIS chiama la funzione FilterAttach di un driver di filtro per allocare e inizializzare le strutture di dati di un modulo di filtro.

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

Sintassi

FILTER_ATTACH FilterAttach;

NDIS_STATUS FilterAttach(
  [in] NDIS_HANDLE NdisFilterHandle,
  [in] NDIS_HANDLE FilterDriverContext,
  [in] PNDIS_FILTER_ATTACH_PARAMETERS AttachParameters
)
{...}

Parametri

[in] NdisFilterHandle

Handle NDIS che identifica un modulo di filtro. Il driver di filtro deve salvare questo handle. L'handle è necessario nelle chiamate successive alle funzioni Xxx di NdisF.

[in] FilterDriverContext

Handle passato al driver Funzione NdisFRegisterFilterDriver che identifica l'area del contesto del driver.

[in] AttachParameters

Puntatore a un oggetto NDIS_FILTER_ATTACH_PARAMETERS struttura che definisce i parametri di inizializzazione per il modulo di filtro.

Valore restituito

FilterAttach restituisce uno dei valori di stato seguenti:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	FilterAttach allocato e inizializzato correttamente le strutture di dati per questo modulo di filtro.
NDIS_STATUS_RESOURCES	FiltroAttach non riuscito a causa di risorse insufficienti.
NDIS_STATUS_FAILURE	FilterAttach restituisce NDIS_STATUS_FAILURE se nessuno dei valori precedenti si applica. Il driver di filtro deve chiamare la funzione NdisWriteEventLogEntry insieme ai parametri che specificano il motivo dell'errore.

Commenti

FilterAttach è una funzione obbligatoria. NDIS chiama la funzione FilterAttach del driver di filtro quando il modulo di filtro specificato si trova nello stato Scollegato . NDIS può chiamare FilterAttach in qualsiasi momento dopo la chiamata alla funzione FilterSetOptions .

All'inizio dell'esecuzione in FilterAttach, il modulo filtro entra nello stato Collegamento .

I driver di filtro devono evitare l'emissione di query OID non necessarie. Usare invece le informazioni in NDIS_FILTER_ATTACH_PARAMETERS, quando disponibile, per ottenere informazioni sui driver sottostanti.

Un driver di filtro esegue le operazioni seguenti quando NDIS chiama FilterAttach.

Crea un'area di contesto per il modulo di filtro e alloca i pool di buffer e qualsiasi altra risorsa.
Chiama la funzione NdisFSetAttributes insieme alla funzione NdisFilterHandle passata a FilterAttach. Il parametro FilterModuleContext di NdisFSetAttributes specifica l'area di contesto del driver di filtro per questo modulo di filtro. NDIS passa questa area di contesto alle funzioni FilterXxx del driver di filtro.
Facoltativamente legge i parametri di configurazione dal Registro di sistema.
Se le operazioni precedenti sono state completate correttamente, il modulo filtro immette lo stato Sospeso .
Se le operazioni precedenti non sono riuscite, il driver di filtro deve rilasciare qualsiasi risorsa allocata nella funzione FilterAttach e restituire il modulo di filtro allo stato Scollegato .
Restituisce NDIS_STATUS_SUCCESS o un codice di errore appropriato.

Un driver di filtro non deve effettuare richieste di invio, indicare i dati ricevuti, effettuare richieste OID o effettuare indicazioni sullo stato di associazione.

NDIS chiama la funzione FilterDetach di un driver di filtro per rilasciare tutte le risorse associate a un modulo di filtro e restituire il modulo di filtro allo stato Scollegato .

NDIS chiama FilterAttach in IRQL = PASSIVE_LEVEL.

Esempi

Per definire una funzione FilterAttach , è prima necessario specificare 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 usando i tipi di funzione 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 FilterAttach denominata "MyAttach ", usare il tipo di FILTER_ATTACH , come illustrato in questo esempio di codice:

FILTER_ATTACH MyAttach;

Implementare quindi la funzione come indicato di seguito:

_Use_decl_annotations_
NDIS_STATUS
 MyAttach(
    NDIS_HANDLE  NdisFilterHandle,
    NDIS_HANDLE  FilterDriverContext,
    PNDIS_FILTER_ATTACH_PARAMETERS  AttachParameters
    )
  {...}

Il tipo di funzione FILTER_ATTACH è definito nel file di intestazione Ndis.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 FILTER_ATTACH 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 NDIS.

Per informazioni su 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 (includere Ndis.h)
IRQL	PASSIVE_LEVEL