Gestione oggetti

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

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 definitivamente, a scopo o dal rundown RPC, il motore di filtro di base interrompe prima qualsiasi transazione esistente.

Quando si crea una nuova sessione, il chiamante può creare una sessione dinamica passando il flag 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, FwpmTransactionCommit0e 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 forzatamente.

Le transazioni sono di sola lettura o di lettura/scrittura e applicano una rigorosa semantica di durabilità con isolamento coerente atomico (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 non riesce 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, nel qual caso non verrà aggiunto alcun filtro.
• Commit della transazione, nel qual caso verranno aggiunti i primi tre filtri.
• Continuare con altre operazioni, incluso il tentativo di ripetizione del FwpmFilterAdd0.

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

Ogni transazione ha anche un timeout di blocco. Si tratta della quantità massima di tempo che può essere proprietaria del blocco. Se il proprietario non rilascia il blocco entro questo periodo di tempo, la transazione viene interrotta forzatamente, 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 forzatamente, la chiamata successiva eseguita all'interno di tale transazione avrà esito negativo con FWP_E_TXN_ABORTED.

Durata degli oggetti

Gli oggetti possono avere una delle quattro durate possibili:

• Dinamico: un oggetto è dinamico solo se viene aggiunto usando un handle di sessione dinamico. Gli oggetti dinamici sono attivi fino a quando non vengono eliminati o la sessione proprietaria termina.
• Statico: gli oggetti sono statici per impostazione predefinita. Gli oggetti statici sono attivi fino a quando non vengono eliminati, l'interruzione BFE o l'arresto del sistema.
• Persistente: gli oggetti permanenti vengono creati passando il flag FWPM_*_FLAG_PERSISTENT appropriato a una funzione Fwpm*Add0. Gli oggetti persistenti sono attivi fino a quando non vengono eliminati.
• Predefinita: gli oggetti predefiniti sono predefiniti da 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 permanenti 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 permanenti, il chiamante può facoltativamente specificare il provider proprietario dell'oggetto. All'avvio del servizio, BFE aggiunge al sistema solo oggetti permanenti se non sono associati a un provider o il provider associato non ha alcun nome di servizio di Windows oppure il servizio Windows associato è impostato su 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 permanente 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 fino a quando non vengono eliminati tutti gli oggetti che vi fanno riferimento.

LUID e GUID

Tutti gli oggetti API WFP (FWPM) in modalità utente sono identificati da un identificatore univoco globale (GUID) e fanno riferimento ad altri oggetti in base al 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 GUID dell'oggetto o lasciarlo inizializzato senza inizializzazione 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 relativo LUID. Il passaggio da GUID a LUID consente al WFP di risparmiare pool non di paging e ottimizzare l'elaborazione in fase di esecuzione. La larghezza del LUID dipende dal tipo di oggetto e varia da un UINT16 a un UINT64. LUID vengono sempre assegnati da BFE.