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.


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


  • 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.

    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.

                                          IFWXSessionFilter ** piSessionFilter,
                                          PFwxFilterHookEvents pFilterHookEvents)
    HRESULT hr = S_OK;
    // Create an instance of the session filter.
    CComObject<CMyFWXSessionFilter> *pSessionFilter;
    hr = CComObject<CMyFWXSessionFilter>::CreateInstance(&pSessionFilter);
    if (SUCCEEDED(hr)) 
        // Give back the required events and the session filter object
        *pFilterHookEvents = m_FwxFilterHookEvents;
        *piSessionFilter = pSessionFilter;
        return S_OK;
    if (FAILED(hr))
        return E_OUTOFMEMORY;


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.


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

Declared in Wspfwext.idl.

See Also


Send comments about this topic to Microsoft

Build date: 6/30/2010