Microsoft Internet Security and Acceleration Server 2004 SDK

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 ISA Server 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. The initialization process can include the creation and initialization of other COM objects that are used in the application filter.

The initial operation of an application filter is invoked by an event. The events for which the filter object representing an application filter will be registered are specified in an FwxFilterHookEvents structure, which can be created and populated during creation of the filter object. The contents of this FwxFilterHookEvents structure are returned to the Firewall service by the call to the FilterInit method.

When a client computer first connects to the ISA Server computer, the Firewall service creates a session object with the standard IFWXSession interface for it. If the Firewall service detects an event for which the application filter is registered when a new user session is opened, it calls the application filter's implementation of the IFWXFilter::AttachToSession method to inform the application filter that the event has occurred. During this call, the application filter creates an instance of an object that implements the IFWXSessionFilter interface. Such an object is called a session filter object.

The session filter object refers to the session object, represented by the IFWXSession interface, for client and user information.

After the Firewall service has called filter's implementation of the IFWXFilter::AttachToSession method, the Firewall service notifies the filter about the events specified in the output of this method by calling the IFWXSessionFilter::FirewallEventHandler method.

When the session filter object is notified by the Firewall service that an event for which the filter is registered has occurred, its FirewallEventHandler method can create an instance of a data filter object, which implements the IFWXDataFilter interface. 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.

The connection object provides the data filter with internal and external sockets by calling IFWXDataFilter::SetSockets. Each socket object implements the IFWXSocket interface. The data filter then performs the data pumping 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.