Microsoft Internet Security and Acceleration Server 2004 SDK

IFWXFilter::FilterInit

The FilterInit method initializes the filter and passes a pointer to the IFWXFirewall interface exposed by the Microsoft Firewall service to it. 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.

HRESULT FilterInit(
  IFWXFirewall* pIFWXFirewall,
  FwxFilterHookEvents* pFilterHookEvents
);

Parameters

pIFWXFirewall: [in] Pointer to the IFWXFirewall interface on the Firewall service.
pFilterHookEvents: [out] Pointer to an FwxFilterHookEvents structure that on return contains the initial set of events that the filter monitors. This structure can be created as a private member of the object that implements this interface, or it can be created by calling the CoTaskMemAlloc function.

Return Values

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

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.

Example Code

The following is an example implementation of the FilterInit method for a filter object that has a private member of type FwxFilterHookEvents.

STDMETHODIMP CMyFilter::FilterInit(IFWXFirewall * pIFWXFirewall,
								 FwxFilterHookEvents * pFilterHookEvents)
{
	// Save the pointer to the IFWXFirewall interface.
	m_spFirewall = pIFWXFirewall;

	// Populate the FwxFilterHookEvents structure.
	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; 

}

Requirements

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