Signaling Events and Alerts

A Web filter can signal any event that is defined in the stored Forefront TMG configuration by calling the IFPCEventDefinition::Signal method on it when a specific situation is detected. The event can be defined by the Web filter during installation or by the Forefront TMG administrator, or it can be one of the predefined Forefront TMG events. When a predefined Forefront TMG event is signaled, it can be specified by the symbolic name for its globally unique identifier (GUID) defined in the FpcEventGuids.h header file in the Inc folder of the Forefront TMG Software Development Kit (SDK).

Alerts, which specify actions to be taken in response to an event and are issued by the Microsoft Firewall service when all the specified conditions are met, can also be defined in the stored Forefront TMG configuration. The actions that can be triggered by an alert include sending an e-mail message, invoking a command, writing to a log, and starting or stopping Forefront TMG services. If your Web filter defines a new event during installation, we recommend that it should also define a corresponding new alert. Alternatively, the Forefront TMG administrator can create an alert for the event programmatically using a script or manually as described in the Forefront TMG product documentation.

To define a new event that your Web filter will signal when, for example, opening a log file fails, include the following steps in the function that registers your filter:

Create an instance of the FPC root object and obtain a smart pointer to the IFPC interface exposed by it.
Call IFPC::GetContainingArray to retrieve a pointer to the IFPCArray interface representing the array.
Call IFPCArray::RuleElements to retrieve a pointer to the IFPCRuleElements interface representing the Firewall service rule elements container.
Call IFPCRuleElements::EventDefinitions to retrieve a pointer to the IFPCEventDefinitions interface representing the collection of events defined in the array.
Call IFPCEventDefinitions::Add to create a new event in the collection.

The following lines of code perform these operations (note that all error checking has been omitted):

HRESULT hr = S_OK;
CComPtr<IFPC> spFPC;
hr = CoCreateInstance(CLSID_FPC,
					NULL,
					CLSCTX_INPROC_SERVER,
					IID_IFPC,
					(LPVOID *)&spFPC);

CComPtr<IFPCArray> spArray;
hr = spFPC->GetContainingArray(&spArray);
CComBSTR bstrEventGuid = LOGERROR_EVENT_GUID;
CComBSTR bstrEventName;
CComBSTR bstrEventDescription;
bstrEventName.LoadString(LOGERROR_EVENT_NAME);
bstrEventDescription.LoadString(LOGERROR_EVENT_DESCRIPTION);
// Open the rule elements container.
CComPtr<IFPCRuleElements> spRuleElements;
hr = spArray->get_RuleElements(&spRuleElements);
// Open the event definitions container.
CComPtr<IFPCEventDefinitions> spEventDefinitions;
hr = spRuleElements->get_EventDefinitions(&spEventDefinitions);
// Add the new event.
CComPtr<IFPCEventDefinition> spEventDefinition;
hr = spEventDefinitions->Add(bstrEventName,
							 bstrEventGuid,
							 NULL,
							 &spEventDefinition);
// Set the event's description and save it.
hr = spEventDefinition->put_Description(bstrEventDescription);
// No need to reload the configuration because filter will 
// be added only after the Firewall service is restarted.
hr = spEventDefinitions->Save(VARIANT_FALSE, VARIANT_FALSE);

To define a new alert that can be issued for the new event and configure it to generate a warning in the Windows event log for alert-triggering occurrences of the event, include the following steps in the function that registers your Web filter:

Call IFPCArray::Alerts to retrieve a pointer to the IFPCAlerts interface representing the collection of alerts that are defined in the array.
Call IFPCAlerts::Add to add an alert for the new event to the collection.
Call the IFPCAlert::Actions property of the interface returned in the previous step to retrieve a pointer to the IFPCAlertAction interface for the new alert.
Call the IFPCAlertActions::SetLogEvent method to create a new action for the alert that will generate a warning in the Windows event log for alert-triggering occurrences of the event.

The following lines of code perform these operations (note that all error checking has been omitted):

CComBSTR bstrAlertName;
CComBSTR bstrAlertDescription;
CComBSTR bstrAlertAction;
bstrAlertName.LoadString(LOGERROR_ALERT_NAME);
bstrAlertDescription.LoadString(LOGERROR_ALERT_DESCRIPTION);
bstrAlertAction.LoadString(LOGERROR_ALERT_LOGACTION);
// Get the alerts container.
CComPtr<IFPCAlerts> spAlerts;
hr = spArray->get_Alerts(&spAlerts);
// Add the new alert.
CComPtr<IFPCAlert> spAlert;
hr = spAlerts->Add(bstrAlertName,
				 bstrEventGuid,
				 NULL, 	
				 -1,
				 &spAlert);
// Set the alert's description, category, and
// severity, and enable the alert.
hr = spAlert->put_Description(bstrAlertDescription);
hr = spAlert->put_Enabled(true);
hr = spAlert->put_Category(fpcOtherAlerts);
hr = spAlert->put_Severity(fpcAlertWarning);
// Configure the alert to generate a warning 
// in the Windows event log.
CComPtr<IFPCAlertActions> spAlertActions;
hr = spAlert->get_Actions(&spAlertActions);
CComPtr<IFPCAlertAction> spAlertAction;
hr = spAlertActions->SetLogEvent(bstrAlertAction, &spAlertAction);
// Save the new alert.
// No need to reload the configuration because filter will 
// be added only after the Firewall service is restarted.
hr = spAlerts->Save(VARIANT_FALSE, VARIANT_FALSE);

Note Events and alerts that are defined during filter installation should be removed when the filter is uninstalled.

To signal the new event, your Web filter should first initialize itself for signaling events by performing the following steps:

Load the string values for the parameters needed to signal the event.
Create an instance of the FPC root object and obtain a smart pointer to the IFPC interface exposed by it.
Call IFPC::GetContainingArray to retrieve a pointer to the IFPCArray interface representing the array.
Call IFPCArray::RuleElements to retrieve a pointer to the IFPCRuleElements interface representing the Firewall service rule elements container.
Call IFPCRuleElements::EventDefinitions to retrieve a pointer to the IFPCEventDefinitions interface representing the collection of events defined in the array.
Call IFPCEventDefinitions::ItemByGuid with the event's GUID to retrieve a pointer to the IFPCEventDefinition interface representing the event's definition.

The following lines of code perform these operations (note that all error checking has been omitted):

m_bstrEventGuid = LOGERROR_EVENT_GUID;
m_bstrEventSource.LoadString(FILTER_NAME);
m_bstrShortDesc.LoadString(LOGERROR_EVENT_SHORT_DESC);
m_bstrLongDesc.LoadString(LOGERROR_EVENT_LONG_DESC);
HRESULT hr = S_OK;
CComPtr<IFPC> spFPC;
hr = CoCreateInstance(CLSID_FPC,
					NULL,
					CLSCTX_INPROC_SERVER,
					IID_IFPC,
					(void**)&spFPC);
CComPtr<IFPCArray> spArray;
hr = spFPC->GetContainingArray(&spArray);
CComPtr<IFPCRuleElements> spRuleElements;
hr = spArray->get_RuleElements(&spRuleElements);
hr = spRuleElements->get_EventDefinitions(&m_spEvents);

After your Web filter initializes itself for signaling events, it can use a separate function to call the IFPCEventDefinition::Signal method on the object representing the new event's definition when a failed attempt to open a log file is detected. The following lines of code perform this operation (note that all error checking has been omitted):

HRESULT hr = S_OK;
CComPtr<IFPCEventDefinition> spEvent;
hr = m_spEvents->ItemByGuid(m_bstrEventGuid, &spEvent);
hr = spEvent->Signal(1, 			// Signal the event once
					 -1, 			 // No additional key
					 m_bstrShortDesc,
					 m_bstrLongDesc,
					 LOGERROR_EVENT_ID,
					 m_bstrEventSource,
					 m_varEmpty,
					 m_varEmpty,
					 0,
					 EVENTLOG_WARNING_TYPE);

Note that the string value specifying the event source (the Web filter) to be recorded in the Windows event log as the source of the event must be included in the following registry value:

HKLM\SYSTEM\CurrentControlSet\Services\
Eventlog\Application(System)\Sources

Send comments about this topic to Microsoft

Build date: 11/30/2009