IFWXDataFilter Interface

Article
08/13/2010

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

For more information about how the IFWXDataFilter interface is used in application filters, see Filter Object Model.

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

Syntax

interface IFWXDataFilter : IUnknown

When To Implement

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

Methods

The IFWXDataFilter interface inherits the methods of the IUnknown interface.

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 from 1024 through 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 2008 R2 or Windows Server 2008 x64 Edition with SP2.
Version	Requires Forefront Threat Management Gateway (TMG) 2010.
Header	Declared in Wspfwext.idl.

Share via