AttachToSession Method of the IFWXFilter Interface

Article
08/13/2010

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

Server	Requires Windows Server 2008 R2 or Windows Server 2008 x64 Edition with SP2.
Version	Requires Forefront Threat Management Gateway (TMG) 2010.
Header	Declared in Wspfwext.idl.

Share via