Implementing a Filter Object

When the Microsoft Firewall service starts, it creates an instance of the registered filter object for each application filter that is installed and enabled. After the instance of each filter object is created, the Firewall service calls its implementation of the FilterInit method to initialize it, passing a pointer to an IFWXFirewall interface and a pointer to an FwxFilterHookEvents structure to receive the initial set of Firewall service network events for which the filter object will be registered.

The call to the FilterInit method is the entry point to the application filter and should be used to initialize all objects of global scope. It also provides an opportunity for the filter to tell the Firewall service which network events are of interest to it.

In the Data Monitor sample, the filter object's contructor sets the initial set of network events in a private data member of type FwxFilterHookEvents. The implementation of the FilterInit method copies the set of network events to the FwxFilterHookEvents structure belonging to the Firewall service. It initializes a member object that signals events and a member object that represents the global policy. It also registers for notification of changes in the global policy and loads the global policy for the first time. This process is shown in the following code.

CDMFilter::CDMFilter()
{
	m_FwxFilterHookEvents.dwGlobalEvents = DWORD(fwx_Connect_Tcp  
												 | fwx_AcceptedConnection 
												 | FWX_ALL_SOURCES);
}
STDMETHODIMP CDMFilter::FilterInit(IFWXFirewall *  pIFWXFirewall,
								 FwxFilterHookEvents * pFilterHookEvents)
{
	DBGTRACEENTRY();
	HRESULT hr;
	// Tell the Firewall service what events we want.
	*pFilterHookEvents = m_FwxFilterHookEvents;
	// Initialize the event signaller.
	CHECK_HR(m_Signaller.Initialize());

	// Initialize the global policy member.
	CComPtr<IFWXFilterAdmin> spFilterAdmin;
	hr = CoCreateInstance(CLSID_FWXFilterAdmin,
						NULL,
						CLSCTX_INPROC_SERVER,
						IID_IFWXFilterAdmin,
						(void**)&spFilterAdmin);
	if (FAILED(hr))
	{
		return hr;
}
	CComPtr<IFPCApplicationFilter> spAppFilter;
	hr = spFilterAdmin->GetFilter(CLSID_DMFilter,&spAppFilter);
	if (FAILED(hr))
	{
		return hr;
}
	hr = m_GlobalPolicy.Initialize(spAppFilter);
	if (FAILED(hr))
	{
		return hr;
}
		 
	// Register for global policy changes.
	hr = RegisterForConfigurationChanges();
	if (FAILED(hr))
	{
		return hr;
}
	// Load the global policy for the first time.
	// (Subsequently, we will get the change notifications)
	(void) LoadGlobalPolicy();
		 
		 return S_OK;
}

When the Firewall service detects an event for which the application filter is registered on a new connection (session) established through the Forefront TMG computer for which the filter has not yet created an instsance of the session filter object, the Firewall service calls the application filter's implementation of the IFWXFilter::AttachToSession method, passes a pointer to the session object representing the new user session to the filter.

The implementation of the AttachToSession method in the Data Monitor sample creates an instance of the filter's session filter object. It passes the set of network events and a pointer to the instance of the session filter object created back to the Firewall service. This process is shown in the following code.

STDMETHODIMP CDMFilter::AttachToSession(IFWXSession * piSession,
										IFWXSessionFilter ** piSessionFilter,
										PFwxFilterHookEvents pFilterHookEvents)
{
	UNREFERENCED_PARAMETER(piSession);
	HRESULT hr = S_OK;
 
	// Create an instance of the session filter object.
	CComObject<CDMSessionFilter> *pSessionFilter;
	hr = CComObject<CDMSessionFilter>::CreateInstance (&pSessionFilter);
	if (FAILED(hr))
	{
		return hr;
}
	pSessionFilter->AddRef();
	pSessionFilter->Initialize(this);
	// Give back the required events and the session filter object.
	*pFilterHookEvents = m_FwxFilterHookEvents;
	*piSessionFilter = pSessionFilter;
	return S_OK;
}

Send comments about this topic to Microsoft

Build date: 11/30/2009