IFWXDataFilter interface

Applies to: desktop apps only

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.

When to implement

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

Members

The IFWXDataFilter interface inherits from the IUnknown interface. IFWXDataFilter also has these types of members:

  • Methods

Methods

The IFWXDataFilter interface has these methods.

Method Description
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.

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.

 

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.

Examples

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

Minimum supported client

None supported

Minimum supported server

Windows Server 2008 R2, Windows Server 2008 with SP2 (64-bit only)

Version

Forefront Threat Management Gateway (TMG) 2010

Header

Wspfwext.idl

See also

Filter Interfaces

 

 

Build date: 7/12/2010