Raising an Event When a String is Found

To inform the system administrator that it found a message containing a string it was seeking, the filter must use an event-raising mechanism. This requires the filter to define an event and make the event available to the administrator through the filter registration process. This event should not be confused with a firewall event. For information on alerts, see Adding a Custom Event and Alert.

The filter must define an alert event, which it will signal whenever a string is found.

Definition of the event should take place during registration of the filter with the Firewall service because you want the administrator to be able to define alerts using this event. When the filter is unregistered, it should remove this event definition. However, the alert for the event should be removed first, or the event removal will fail. If the event is not removed, then when the filter is re-registered, you will receive an error for attempting to create a file that already exists.

To create an alert event

1. Register alert events in ISA by adding the following code to SMTPFLTR.cpp:

   #define FILTER_EVENT_NAME_STRING "SMTP Filter Event"
   #define FILTER_EVENT_DESCRIPTION_STRING "SMTP Filter Event"
   

   Add the code shown in bold to the function RegisterFWXFilter in SMTPFLTR.cpp:

   MSFPCCOM::IFPCFilterProtocolPtr comptrIFPCFilterProtocol; 
   MSFPCCOM::IFPCPtr comptrIFPC;
   MSFPCCOM::IFPCEventDefinitionPtr  comptrIFPCEventDefinition;
   //Create an instance of ISA admin object
   comptrIFPC.CreateInstance(MSFPCCOM::CLSID_FPC);
   
   	CComPtr<IFWXFilterAdmin> pIFWXFilterAdmin;
    
   	hr = CoCreateInstance (CLSID_FWXFilterAdmin,
   				NULL,
   				CLSCTX_SERVER,
   				IID_IFWXFilterAdmin,
   				(LPVOID *) &pIFWXFilterAdmin);
   	if (FAILED(hr))
   		return hr;
   
   	//Create an instance of the ISA admin object. The Scope parameter is used to select the right object:
   	//For enterprise scope, use CLSID_FPCDS; otherwise use CLSID_FPC.
   	hr = comptrIFPC.CreateInstance((Scope == fwx_EnterpriseScope) ? MSFPCCOM::CLSID_FPCDS : MSFPCCOM::CLSID_FPC);
   	if (FAILED(hr))
   		return hr;
   

   The following code shown in bold should be added to the registration code in the try-catch block:

   try
   {
   //Create a new event for this filter. The reason this
   //code is inside a try-catch block is that if this event
   //already exists, an exception will be raised
   comptrIFPCEventDefinition = 
   	comptrIFPC->Arrays->GetContainingArray()->PolicyElements->EventDefinitions->Add(FILTER_EVENT_DESCRIPTION_STRING,_bstr_t(FILTER_GUID_STRING),NULL);
   comptrIFPCEventDefinition->Description = FILTER_EVENT_DESCRIPTION_STRING;
   comptrIFPCEventDefinition->Name = FILTER_EVENT_NAME_STRING;
   comptrIFPCEventDefinition->Save();
   }
   catch(_com_error& err)
   {
   	//If the event already exists, it is not considered an error
   	if(err.Error() != HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS))
   		return err.Error();
   }
   

   The following should be added to the unregistration code of the RegisterFWXFilter function:

   //Remove the event
   comptrIFPC->Arrays->GetContainingArray()->PolicyElements->EventDefinitions->Remove(FILTER_GUID_STRING);
   //Save the change
   comptrIFPC->Arrays->GetContainingArray()->PolicyElements->EventDefinitions->Save();
   

2. Create an alert that uses the SMTP event

   See the ISA product documentation for help in creating a new alert.

3. Signal event when the string is found

   To raise an event the filter must use the alert service API.

   1. Add the file alertsrv.idl to the project; then add the following code to Stdafx.h:

      #import "alertsrv.tlb" rename_namespace("ALERTSRVLib") named_guids
      

   2. Add a private member to CSMTPDataFilter class in SMTPDataFilter.h:

      ALERTSRVLib::IFpcAlertNotificationPtr m_comptrIFPCAlertNotification;
      

   3. Add the following code to the CSMTPDataFilter::Initialize function in SMTPDataFilter.cpp:

      hr=m_comptrIFPCAlertNotification.CreateInstance(ALERTSRVLib::CLSID_FpcAlertNotification);
      

   Now the filter can call the IFPCAlertNotification::SignalEvent method of this object to signal when the event occurs.

4. Build the project.
5. Follow the Filter Setup procedure to install the filter.