FilterInit Method of the IFWXFilter Interface

The FilterInit method initializes the filter, passes a pointer to the IFWXFirewall interface exposed by the Microsoft Firewall service to the filter, and populates an FwxFilterHookEvents structure created by the Firewall service with the initial set of events for which the filter should be notified.

The Firewall service calls this method for each application filter that is installed on the Forefront TMG computer and enabled after it creates an instance of the COM object that implements the IFWXFilter interface in the filter.

The IFWXFirewall interface provides access to Firewall service functions that are not tied to any specific user session. For a list of the general methods, see the IFWXFirewall interface.

Syntax

HRESULT FilterInit(
  [in]   IFWXFirewall* pIFWXFirewall,
  [out]  FwxFilterHookEvents* pFilterHookEvents
);

Parameters

pIFWXFirewall

Pointer to the IFWXFirewall interface exposed by the Firewall service.

pFilterHookEvents

Pointer to an FwxFilterHookEvents structure that on return contains the initial set of events for which the filter should be notified. This set of events is specified by a combination of values from the FwxFirewallEventType, FwxFirewallEventSource, and FwxFirewallEventProtocolSource enumerated types that is formed using the bitwise OR operator.

Return Value

Implementations of this method should handle any run-time error and return S_OK. For more information, see Remarks.

Example Code

The following is an example implementation of the FilterInit method for a filter object that has a private data member of type FwxFilterHookEvents containing the initial set of events for which the filter should be notified.

STDMETHODIMP CMyFilter::FilterInit(IFWXFirewall * pIFWXFirewall,
								 FwxFilterHookEvents * pFilterHookEvents)
{
	// Save the pointer to the IFWXFirewall interface.
	m_spFirewall = pIFWXFirewall;
	// Populate the FwxFilterHookEvents structure in the private member.
	m_FwxFilterHookEvents.dwGlobalEvents = DWORD(fwx_Connect_Tcp |
												 fwx_AcceptedConnection |
												 fwxSourceWSP |
												 fwxSourceNAT);
	// Pass the initial set of events that the filter monitors
	// to the Firewall service.
	*pFilterHookEvents = m_FwxFilterHookEvents;
	// Perform other initialization tasks.
	// Return S_OK when finished.
	return S_OK; 
}

Remarks

Implementations of the FilterInit method should include all initializations, particularly events to monitor, as well as the reading of configurations and the creation of listening sockets.

If FilterInit does not succeed, as in a case where resources required by the filter are absent, this method should still return S_OK, but not register for any events. This will reduce the risk that the Firewall service will fail to start.

The FilterInit method should not return until the filter is in a valid state and is fully initialized. When the FilterInit method of a filter returns, the Firewall service assumes that the filter is fully initialized. If the implementation of the FilterInit method is asynchronous and it continues to perform initialization steps after returning, traffic can be sent through the filter when it is not yet in a valid state.

Requirements

See Also

IFWXFilter

Send comments about this topic to Microsoft

Build date: 11/30/2009