AttachToSession Method of the IFWXFilter Interface

The AttachToSession method creates an instance of the session filter object, returns a pointer to the IFWXSessionFilter interface on the object created, and populates an FwxFilterHookEvents structure created by the Firewall service with the set of events that the session filter will handle. This set of events may differ from the events specified in the IFWXFilter::FilterInit method.

The Microsoft Firewall service calls this method when it detects an event for which the filter is registered on a connection (session) established through the Forefront TMG computer for which the filter has not yet created an instance of the session filter object.

Syntax

HRESULT AttachToSession(
  [in]	 IFWXSession* piSession,
  [out]	IFWXSessionFilter** piSessionFilter,
  [in, out]  PFwxFilterHookEvents pFilterHookEvents
);

Parameters

piSession

Pointer to the IFWXSession interface associated with the session to be monitored.

piSessionFilter

Address of a variable that receives a pointer to the IFWXSessionFilter interface on the session filter object created. The session filter object receives event notifications for a session.

pFilterHookEvents

Pointer to an FwxFilterHookEvents structure that on return contains the set of events that the filter handles. 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 return the following:

S_OK

The method succeeded.

E_OUTOFMEMORY

Not enough memory or resources could be allocated to process the event. This will cause the request that generated the event to fail.

Example Code

The following is an example implementation of the AttachToSession method.

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

Remarks

After the Firewall service receives a pointer to the IFWXSessionFilter interface for a specific user session, the Firewall service starts sending notifications to the filter about events in the session that the filter is registered to handle by calling the FirewallEventHandler method on the IFWXSessionFilter interface for the session.

Requirements

See Also

IFWXFilter

Send comments about this topic to Microsoft

Build date: 11/30/2009