Filter Object Model

When the Microsoft Firewall service starts, it exposes the IFWXFirewall interface, which provides access to Firewall service functions.

An application filter must include a COM object that implements the IFWXFilter interface. This object is called the filter object. When the Firewall service starts, it creates an instance of the filter object for each application filter that is installed on the Forefront TMG computer and enabled. The Firewall service initializes each application filter by calling the application filter's implementation of the FilterInit method on the IFWXFilter interface and passing pointers to the IFWXFirewall interface exposed by the Firewall service and to an FwxFilterHookEvents structure created by the Firewall service.

The operations of an application filter are invoked by event notifications. The FilterInit method must populate the FwxFilterHookEvents structure provided by the Firewall service with the initial set of events for which the filter should be notified. The initialization process can include the creation and initialization of other COM objects that are used in the application filter.

When a client computer first connects to the Forefront TMG computer, the Firewall service creates a session object that exposes the IFWXSession interface for it. Then, when the Firewall service detects an event for which the application filter is registered in the new user session, it calls the application filter's implementation of the IFWXFilter::AttachToSession method with pointers to the IFWXSession interface for the session and the FwxFilterHookEvents structure to inform the application filter that the event has occurred.

During this call, the application filter creates an instance of the filter's object that implements the IFWXSessionFilter interface. This object is called the session filter object. The session filter object refers to the session object, represented by the IFWXSession interface, for client and user information. The implementation of IFWXFilter::AttachToSession should populate the FwxFilterHookEvents structure provided by the Firewall service with the set of events that the session filter will handle. This set of events may differ from the events specified in the IFWXFilter::FilterInit method.

After the Firewall service has called filter's implementation of the IFWXFilter::AttachToSession method, the Firewall service notifies the filter about events in the user session for which the filter is registered by calling the IFWXSessionFilter::FirewallEventHandler method.

For an event of the fwx_AcceptedConnection, fwx_Bind_Udp, fwx_Connect_Tcp, or fwx_Udp_Destination type, the implementation of the FirewallEventHandler method can create an instance of the filter's data filter object, which implements the IFWXDataFilter interface. The implementation of this method can then obtain a pointer to the applicable IFWXConnection interface from the FwxFirewallEvent structure provided in the pFirewallEvent parameter, and then call the AttachDataFilter method on this interface to attach the data filter to it.

Alternatively, a data filter object can be created by using IFWXSession::SetDataFilterFactory. The session filter object attaches the data filter object to the connection object related to the specific event.

In either case, the Firewall service responds by providing two sockets that implement the IFWXSocket interface in a call to the IFWXDataFilter::SetSockets method, and the filter can start pumping data and filtering for the specific connection.

Application filters follow an active data-pumping programming model, where an application filter that registers itself on a connection takes full ownership of the connection and actively pipes the data through from one side to the other. This model is similar to I/O completion ports, where a filter dispatches I/O requests and receives notifications upon completion of the I/O operation. Although the application filter SDK hides the details of the worker-thread implementation, it is important to be aware of how this works and to realize that I/O completions for the same connection can be called in the context of different threads.

Application filters can be chained so that the same protocol is handled by more than one filter. This is achieved by using the virtual socket concept through the IFWXSocket interface. When an application filter pumps data through a socket interface, it can be a virtual socket that is actually connected to the next filter, or it can be a real network socket that actually writes and reads data from the network.

Data is received as buffers. To avoid the need to copy buffers, each buffer is created as an object that implements the IFWXIOBuffer interface. Because data is received asynchronously, the data filter must implement IFWXIOCompletion, which is necessary for asynchronous (I/O) on the sockets. When an asynchronous I/O operation is completed, the Firewall service uses IFWXIOCompletion::CompleteAsyncIO to notify the data filter that the buffer is available to it.

The data filter can then perform its filtering function on the data buffer.

Filter registration procedures are described in Filter Setup.

The phases of a filter's operation are shown in the following figure.

Send comments about this topic to Microsoft

Build date: 6/30/2010