ReloadWPXFilterConfiguration Callback Function

Article
08/13/2010

The ReloadWPXFilterConfiguration function is called by the Forefront TMG Web proxy to notify a Web filter that changes to the configuration of the Forefront TMG administration COM objects have been applied as a result of a call to a Save method. You can use this function to perform operations to update the Web filter by reloading the saved configuration of the Forefront TMG administration COM objects from persistent storage.

The declaration of the ReloadWPXFilterConfiguration function is:

Syntax

BOOL WINAPI ReloadWPXFilterConfiguration(void);

Parameters

This callback has no parameters.

Return Value

The implementation of this function should return TRUE if the filter is successfully updated with respect to changes in the stored Forefront TMG configuration or FALSE if reloading of any part of the configuration fails. If a failure occurs, the filter must call SetLastError with an error code that indicates the nature of the failure before returning FALSE.

Remarks

Forefront TMG provides a mechanism to enable Web filters to be updated when changes are made to objects in the stored configuration. This mechanism also provides a means of indicating to the user whether changes were successfully applied (reloaded by the Web filter). If not, an event can be written to the event log.

Calls to a Save method return as soon as the information is written to the Configuration Storage server, and each Forefront TMG computer periodically polls its Configuration Storage server for configuration changes that need to be retrieved, written to the configuration stored in the registry, and reloaded by the Forefront TMG services, application filters, and Web filters. When a Forefront TMG computer retrieves configuration changes from the Configuration Storage server after a call to a Save method returns successfully, the Forefront TMG services reload the modified configuration. In Forefront TMG, the fReloadConfiguration parameter is ignored.

A call to a Save method with the default parameter values ensures only that configuration changes that can be applied dynamically without restarting the Microsoft Firewall service take effect. Changes that require restarting of the Firewall service are applied as a result of a call to a Save method only if the fResetRequiredServices parameter is set to VARIANT_TRUE. For more information, see Restarting Services After Configuration Changes.

After the Firewall service reloads the saved configuration with the most recent changes from persistent storage, it notifies the Web proxy. The Web proxy then calls ReloadWPXFilterConfiguration in each registered Web filter after it has reloaded the most recent changes from persistent storage.

If a Web filter fails to reload any part of the configuration, the implementation of ReloadWPXFilterConfiguration should call SetLastError with an appropriate error code and return FALSE. When FALSE is returned to the Web proxy, the Web proxy passes the error code set by the Web filter in the call to SetLastError back to the Firewall service. The Firewall service then signals an event that specifies the error code received from the Web proxy and the name of the Web filter. By default, this event triggers an alert that records the details of the event in the event log.

In Forefront TMG, the call to a Save method does not fail when ReloadWPXFilterConfiguration returns FALSE and the Web proxy passes an error code back to the Firewall service because the call to the Save method already returned successfully when the information was written to the Configuration Storage server.

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 Wpxhttpfilt.h.

Share via