Gestione oggetti

Questa sezione illustra l'uso corretto dei tipi di oggetti API di Windows Filtering Platform (WFP).

Sessioni

L'API WFP è orientata alla sessione e la maggior parte delle chiamate di funzione viene effettuata nel contesto di una sessione. Viene creata una nuova sessione client chiamando FwpmEngineOpen0. La sessione termina quando il client chiama FwpmEngineClose0 o il processo client termina. Quando una sessione viene eliminata, a scopo o in base all'esecuzione RPC, il motore di filtro di base (BFE) interrompe prima qualsiasi transazione esistente.

Quando si crea una nuova sessione, il chiamante può creare una sessione dinamica passando il flag di FWPM_SESSION_FLAG_DYNAMIC a FwpmEngineOpen0. Tutti gli oggetti aggiunti durante una sessione dinamica vengono eliminati automaticamente al termine della sessione.

Transazioni

L'API WFP è transazionale e la maggior parte delle chiamate di funzione viene effettuata nel contesto di una transazione. I chiamanti possono usare FwpmTransactionBegin0, FwpmTransactionCommit0 e FwpmTransactionAbort0 per controllare in modo esplicito le transazioni. Tuttavia, se una chiamata di funzione viene eseguita all'esterno di una transazione esplicita, verrà eseguita all'interno di una transazione implicita. Se una transazione è in corso, quando una sessione termina, viene interrotta automaticamente. Le transazioni implicite non vengono mai interrotte.

Le transazioni sono di sola lettura o di sola lettura/scrittura e applicano una semantica rigorosa della semantica Atomic Consistent Isolated Durable (ACID).

Ogni sessione client può avere una sola transazione in corso alla volta. Se il chiamante tenta di avviare una seconda transazione prima di eseguire il commit o l'interruzione del primo, BFE restituisce un errore.

Se un'operazione ha esito negativo durante il corso di una transazione, non influisce sullo stato complessivo della transazione. Si supponga, ad esempio, che il client inizi una transazione e chiami correttamente FwpmFilterAdd0 tre volte prima che una quarta chiamata abbia esito negativo. Il client ha ora la possibilità di:

• Interruzione della transazione, in cui nessuno dei filtri verrà aggiunto.
• Commit della transazione, in cui verranno aggiunti i primi tre filtri.
• Continuare con altre operazioni, incluso il tentativo di ripetizione del tentativo di FwpmFilterAdd0 non riuscito.

Quando si inizia una transazione, BFE attenderà fino alla scadenza del txnWaitTimeoutInMSec della sessione per acquisire il blocco. Se il blocco non viene acquisito entro questo periodo, l'acquisizione del blocco (e la chiamata FwpmTransactionBegin0 ) avrà esito negativo. Ciò impedisce ai client di non rispondere in modo indefinito. Se il client non ha specificato un timeout di blocco, il valore predefinito è 15 secondi.

Ogni transazione ha anche un timeout di blocco. Questo è il tempo massimo che può essere proprietario del blocco. Se il proprietario non rilascia il blocco entro questo periodo, la transazione viene interrotta in modo forcibizzato, causando il rilascio del blocco. Il timeout di blocco non è configurabile. È infinito per i chiamanti in modalità kernel e un'ora per i chiamanti in modalità utente. Se una transazione viene interrotta, la chiamata successiva eseguita all'interno di tale transazione avrà esito negativo con FWP_E_TXN_ABORTED.

Durata dell'oggetto

Gli oggetti possono avere una delle quattro possibili durata:

• Dinamico: un oggetto è dinamico solo se viene aggiunto usando un handle di sessione dinamico. Gli oggetti dinamici vengono attivati fino a quando non vengono eliminati o termina la sessione di proprietà.
• Statico: gli oggetti sono statici per impostazione predefinita. Gli oggetti statici non vengono distribuiti finché non vengono eliminati, BFE arresta o il sistema non viene arrestato.
• Persistente: gli oggetti persistenti vengono creati passando il flag di FWPM_*_FLAG_PERSISTENT appropriato a una funzione Fwpm*Add0 . Gli oggetti persistenti non vengono eliminati.
• Predefinita: gli oggetti predefiniti sono predefiniti di BFE e non possono essere aggiunti o eliminati. Vivono per sempre.

I filtri nei livelli in modalità kernel possono essere contrassegnati come filtri di avvio passando il flag appropriato a FwpmFilterAdd0. I filtri di avvio vengono aggiunti al sistema all'avvio del driver TCP/IP e rimossi al termine dell'inizializzazione BFE. Gli oggetti persistenti vengono aggiunti all'avvio di BFE.

In molti casi, un provider di criteri potrebbe non voler applicare i criteri persistenti se il provider è stato disabilitato. Quando si aggiunge un provider, il chiamante può specificare un nome di servizio Windows facoltativo. Quando si aggiungono oggetti persistenti, il chiamante può facoltativamente specificare il provider proprietario di tale oggetto. All'avvio del servizio, BFE aggiunge solo oggetti persistenti al sistema se non sono associati a un provider o il provider associato non ha alcun nome del servizio Windows o il servizio Windows associato è impostato sull'avvio automatico.

Associazioni di oggetti

Alcuni oggetti hanno riferimenti ad altri oggetti. Ad esempio, un filtro fa sempre riferimento a un livello e può fare riferimento a un callout e a un contesto del provider. Gli oggetti non possono fare riferimento a oggetti che possono avere una durata più breve. Pertanto, un oggetto dinamico non può fare riferimento a un oggetto dinamico da una sessione diversa. Un oggetto statico non può fare riferimento a un oggetto dinamico. Un oggetto persistente non può fare riferimento a un oggetto dinamico, a un oggetto statico o a un oggetto persistente di proprietà di un provider diverso.

Non è possibile eliminare un oggetto finché tutti gli oggetti che fanno riferimento sono stati eliminati.

ID e GUID

Tutti gli oggetti API WFP in modalità utente (FWPM) vengono identificati da un identificatore univoco globale (GUID) e fanno riferimento ad altri oggetti dal GUID. Il GUID deve essere univoco solo all'interno del tipo di oggetto. Ad esempio, un filtro e un contesto del provider possono avere lo stesso GUID, ma due filtri non possono. Quando si aggiunge un nuovo oggetto, i chiamanti possono assegnare il GUID dell'oggetto o lasciarlo inizializzato zero e consentire a BFE di assegnare il GUID.

Tutti gli oggetti API WFP in modalità kernel (FWPS) sono identificati da un identificatore univoco locale (LUID) e fanno riferimento ad altri oggetti dal loro LUID. Il passaggio da GUID a LUID consente al WFP di risparmiare pool non a pagina e ottimizzare l'elaborazione in fase di esecuzione. La larghezza del LUID dipende dal tipo di oggetto ed è compreso tra un UINT16 e un UINT64. L's LUIDviene sempre assegnato da BFE.