Gerenciamento de objetos

Esta seção aborda o uso correto dos tipos de objeto da API da Plataforma de Filtragem do Windows (WFP).

Sessões

A API WFP é orientada a sessão e a maioria das chamadas de função são feitas dentro do contexto de uma sessão. Uma nova sessão de cliente é criada chamando FwpmEngineOpen0. A sessão termina quando o cliente chama FwpmEngineClose0 ou o processo do cliente termina. Quando uma sessão é destruída, seja de propósito ou pelo rundown RPC, o BFE (Base Filtering Engine) primeiro anula qualquer transação existente.

Ao criar uma nova sessão, o chamador pode criar uma sessão dinâmica passando o sinalizador de FWPM_SESSION_FLAG_DYNAMIC para FwpmEngineOpen0. Todos os objetos adicionados durante uma sessão dinâmica são excluídos automaticamente quando a sessão termina.

Transações

A API WFP é transacional e a maioria das chamadas de função são feitas dentro do contexto de uma transação. Os chamadores podem usar FwpmTransactionBegin0 , FwpmTransactionCommit0e FwpmTransactionAbort0 para controlar explicitamente as transações. No entanto, se uma chamada de função for feita fora de uma transação explícita, ela será executada dentro de uma transação implícita. Se uma transação estiver em andamento, quando uma sessão for encerrada, ela será automaticamente anulada. As transações implícitas nunca são abortadas à força.

As transações são somente leitura ou leitura/gravação e impõem semântica rigorosa de Atomic Consistent Isolated Durable (ACID).

Cada sessão de cliente pode ter apenas uma transação em andamento de cada vez. Se o chamador tentar iniciar uma segunda transação antes de confirmar ou abortar a primeira, o BFE retornará um erro.

Se uma operação falhar durante o curso de uma transação, isso não afetará o estado geral da transação. Por exemplo, suponha que o cliente inicia uma transação e chama com êxito FwpmFilterAdd0 três vezes antes que uma quarta chamada falhe. O cliente tem agora a opção de:

• Anular a transação, caso em que nenhum dos filtros será adicionado.
• Confirmando a transação, caso em que os três primeiros filtros serão adicionados.
• Continuando com mais operações, incluindo potencialmente tentar novamente o FwpmFilterAdd0 com falha.

Ao iniciar uma transação, o BFE aguardará até que o txnWaitTimeoutInMSec da sessão expire para adquirir o bloqueio. Se o bloqueio não for adquirido dentro desse período, a aquisição do bloqueio (e a chamadaFwpmTransactionBegin0) falhará. Isso evita que os clientes deixem de responder indefinidamente. Se o cliente não tiver especificado um tempo limite de bloqueio, o padrão será de 15 segundos.

Cada transação também tem um tempo limite de bloqueio. Esta é a quantidade máxima de tempo que ele pode possuir a fechadura. Se o proprietário não liberar o bloqueio dentro desse prazo, a transação é abortada à força, fazendo com que o bloqueio seja liberado. O tempo limite de bloqueio não é configurável. É infinito para chamadores de modo kernel e uma hora para chamadores de modo de usuário. Se uma transação for abortada à força, a próxima chamada feita dentro dessa transação falhará com FWP_E_TXN_ABORTED.

Tempo de vida do objeto

Os objetos podem ter um dos quatro tempos de vida possíveis:

• Dinâmico — Um objeto é dinâmico somente se for adicionado usando um identificador de sessão dinâmico. Os objetos dinâmicos vivem até serem excluídos ou a sessão proprietária ser encerrada.
• Estático — Os objetos são estáticos por padrão. Os objetos estáticos vivem até serem excluídos, o BFE parar ou o sistema ser desligado.
• Persistente — Os objetos persistentes são criados passando o sinalizador FWPM_*_FLAG_PERSISTENT apropriado para uma função Fwpm*Add0. Os objetos persistentes vivem até serem excluídos.
• Built-in — Os objetos internos são predefinidos pelo BFE e não podem ser adicionados ou excluídos. Eles vivem para sempre.

Os filtros em camadas de modo kernel podem ser marcados como filtros de tempo de inicialização passando o sinalizador apropriado para FwpmFilterAdd0. Os filtros de tempo de inicialização são adicionados ao sistema quando o driver TCP/IP é iniciado e removidos quando o BFE termina a inicialização. Objetos persistentes são adicionados quando o BFE é iniciado.

Em muitos casos, um provedor de políticas pode não querer que sua política persistente seja aplicada se o provedor tiver sido desativado. Ao adicionar um provedor, o chamador pode especificar um nome de serviço opcional do Windows. Ao adicionar objetos persistentes, o chamador pode, opcionalmente, especificar o provedor que "possui" esse objeto. No início do serviço, o BFE só adiciona objetos persistentes ao sistema se eles não estiverem associados a um provedor, ou se o provedor associado não tiver um nome de serviço do Windows, ou se o serviço do Windows associado estiver definido para iniciar automaticamente.

Associações de objetos

Alguns objetos têm referências a outros objetos. Por exemplo, um filtro sempre faz referência a uma camada e pode fazer referência a um texto explicativo e a um contexto de provedor. Os objetos não podem referir-se a objetos que podem ter uma vida útil mais curta. Assim, um objeto dinâmico não pode se referir a um objeto dinâmico de uma sessão diferente. Um objeto estático não pode se referir a um objeto dinâmico. Um objeto persistente não pode se referir a um objeto dinâmico, um objeto estático ou um objeto persistente de propriedade de um provedor diferente.

Um objeto não pode ser excluído até que todos os objetos que fazem referência a ele tenham sido excluídos primeiro.

LUIDs e GUIDs

Todos os objetos de API do WFP (FWPM) de modo de usuário são identificados por um identificador globalmente exclusivo (GUID) e fazem referência a outros objetos por seus GUIDs. O GUID só precisa ser exclusivo dentro do tipo de objeto. Por exemplo, um filtro e um contexto de provedor podem ter o mesmo GUID , mas dois filtros não podem. Ao adicionar um novo objeto, os chamadores podem atribuir o GUID do objeto ou deixá-lo inicializado a zero e permitir que o BFE atribua o GUID .

Todos os objetos de API WFP (FWPS) do modo kernel são identificados por um identificador localmente exclusivo (LUID) e fazem referência a outros objetos por seu LUID. A mudança de GUID para LUID permite que o WFP conserve o pool não paginado e otimize o processamento em tempo de execução. A largura do LUID depende do tipo de objeto e varia de um UINT16 a um UINT64. LUIDs são sempre atribuídos pela BFE.