Microsoft Internet Security and Acceleration Server 2004 SDK

IFWXDataFilter

The IFWXDataFilter interface represents a data filter. A data filter functions as the data pump of the Microsoft Firewall service and performs data filtering.

Note When you use the IFWXDataFilter interface, consider possible threading issues. For more information, see Best Practices.

When To Implement

An application filter that needs to hook into the data pump of the Firewall service must implement this interface.

Methods in Vtable Order

The IFWXDataFilter interface inherits the methods of the standard COM interface IUnknown.

In addition, IFWXDataFilter defines the following methods.

Method	Description
SetSockets	Sets the internal and external sockets for the data filter. When this method is called, the filter is expected to begin the data-pumping process between the sockets.
Detach	Detaches the data filter from the internal and external sockets attached to it. This method should release the references that the data filter object holds to the socket interfaces and to the connection.

Remarks

Filters that examine data require a data pump to pass data through the connection.

There are two approaches to creating data filter instances:

Implement IFWXConnection::AttachDataFilter to create and attach a data filter by adding code to the session filter. The session filter will then attach a data filter instance to the connection whenever the registered event occurs.
Provide an object that implements the standard COM IClassFactory interface.

Implement the IFWXConnection interface methods (implemented by the Firewall service) to attach the data pump, and IFWXSessionFilter::FirewallEventHandler to receive information about the event. Through the IFWXDataFilter::SetSockets method, the Firewall service provides socket interfaces to the data filter for the sockets on the internal and external computers. The Firewall service calls the IFWXDataFilter::Detach method when the connection to the sockets is no longer needed. When IFWXDataFilter::Detach is called, you must code a release to the sockets so that the system can delete the socket objects.

The Firewall service calls IFWXIOCompletion::CompleteAsyncIO when the I/O operation is completed. The data filter object inherits the CompleteAsyncIO method from IFWXIOCompletion. The data is then available for the data pump and filter.

Handling Data Received from Another Protocol

When the primary port of a protocol lies within the dynamic port range (1024 – 5000), a filter for that protocol will receive a Firewall service event if that port is selected for another protocol's secondary connection. However, when the data stream through that secondary connection does not comply with the filter's expected protocol, the filter must be able to handle this situation.

The proper approach is to design a filter to revert to a simple data pump if the data stream is not the expected protocol. Note that it is possible for data that would have been rejected at the primary port to pass through the filter at the secondary port.

Example Code

The following is a standard declaration of the data filter object.

//Note that IFWXIOCompletion::CompleteAsyncIO is made
//public in this declaration, and must be implemented 
//by this object.
class ATL_NO_VTABLE CDumpData :
	public CComObjectRootEx<CComMultiThreadModel>,
	public IFWXDataFilter,
	public IFWXIOCompletion
{

Requirements

Server: Requires Windows Server 2003 or Windows 2000.
Version: Requires Internet Security and Acceleration Server 2004.
Header: Declared in Wspfwext.idl.