IFPCWebFilters::Add method

Article
08/27/2012

Applies to: desktop apps only

The Add method creates a new FPCWebFilter object in the collection and returns a reference to it.

Syntax

HRESULT Add(
  [in]   BSTR Guid,
  [in]   BSTR Name,
  [in]   BSTR RelativePath,
  [in]   FpcFilterPriority Priority,
  [in]   FpcFilterDirection Direction,
  [out]  IFPCWebFilter **ppNewFilter
);

FPCWebFilters.Add( _
  ByVal Guid As String, _
  ByVal Name As String, _
  ByVal RelativePath As String, _
  ByVal Priority As FpcFilterPriority, _
  ByVal Direction As FpcFilterDirection, _
  ByRef ppNewFilter As IFPCWebFilter _
) As FPCWebFilter

Parameters

Guid [in]

C++ Required. BSTR that specifies the globally unique identifier (GUID) of the new filter.

VB Required. String that specifies the globally unique identifier (GUID) of the new filter.
Name [in]

C++ Required. BSTR that specifies the display name of the new filter.

VB Required. String that specifies the display name of the new filter.

RelativePath [in]

C++	Required. BSTR that specifies the path of the filter's dynamic-link library (DLL), including the file name of the DLL, relative to the Forefront TMG installation folder (such as C:\Program Files\Microsoft ISA Server\).
VB	Required. String that specifies the path of the filter's dynamic-link library (DLL), including the file name of the DLL, relative to the Forefront TMG installation folder (such as C:\Program Files\Microsoft ISA Server\).

Priority [in]
Required. Value from the FpcFilterPriority enumerated type that specifies the priority of the new filter. The possible values are fpcFilterPriority_Low, fpcFilterPriority_Medium, or fpcFilterPriority_High.
Direction [in]
Required. Value from the FpcFilterDirection enumerated type that specifies whether the new Web filter is to be invoked in the forward proxy scenario, in the reverse proxy scenario, or in both scenarios.
ppNewFilter [out]
Address of an interface pointer that on return points to the new IFPCWebFilter interface created.

Return value

C++

This method can return one of the following:

S_OK, indicating that the operation succeeded.
An error code, indicating that the operation failed. In this case, the [out] parameter returned is a null object.

VB

This method returns a reference to an FPCWebFilter object if successful. Otherwise, an error is raised that can be intercepted by using an error handler.

Remarks

For a Web filter to work on a Forefront TMG computer, its dynamic-link library (DLL) must be copied to the computer, an object representing it must be created in the FPCWebFilters collection for the computer's array, and it must be registered as an extension of the Forefront TMG Web proxy on the computer by including a reference to it in the computer's InstalledWebFilters property.

When the Add method is called on an array member to register a Web filter in an array, a reference to the new FPCWebFilter object is automatically created in the FPCRefs collection stored in the InstalledWebFilters property of the local Forefront TMG computer. The Add method should not be called on two members of the same array simultaneously.

When an enterprise with central array management is deployed, objects representing Web filters can also be added to the FPCWebFilters collection in the enterprise configuration. If the same Web filter is added to the FPCWebFilters collections in the enterprise configuration and an array configuration with different values for the Direction parameter, which sets the FilterDirection property of the Web filter, the enterprise setting overrides the array setting. Conversely, the values of the RelativePath and Priority parameters are not used at the enterprise level.

When an enterprise with central array management is deployed, the Add method can be used to add a Web filter to the configuration of an empty array.

For more information about registering Web filters, see Web Filter Setup.

Examples

This VBScript script creates an FPCWebFilter object that represents a Web filter called My Filter in the FPCWebFilters collection for the containing array, sets some of the filter's properties, and enables the filter. It does not include error handling.

' Create the constants needed
Const filterGuid = "{5b6f6af3-3928-44a3-90f6-c96295c51da6}"
Const filterName = "My Filter"
Const relativePath = "MyFilter\Bin\MyFilter.dll"
Const fpcFilterPriority_High = 2
Const fpcFilterDirectionBoth = 2
Const filterDesc = "This Web filter protects networks."
Const vendorName = "Widgets"
Const filterVersion = "1.0"
' Create the root object.
Dim root  ' The FPCLib.FPC root object
Set root = CreateObject("FPC.Root")
' Declare the other objects needed.
Dim tmgArray  ' An FPCArray object
Dim filters   ' An FPCWebFilters collection
Dim filter    ' An FPCWebFilter object
' Get references to the array object 
' and the Web filters collection.
Set tmgArray = root.GetContainingArray()
Set filters = tmgArray.Extensions.WebFilters
' Add the new Web filter to the collection.
Set filter = filters.Add(filterGuid, filterName, relativePath, fpcFilterPriority_High, fpcFilterDirectionBoth)
filter.Description = filterDesc
filter.Vendor = vendorName
filter.Version = filterVersion
filter.Enabled = True
filters.Save
WScript.Echo "Done!"

Requirements

Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008 R2, Windows Server 2008 with SP2 (64-bit only)
Version	Forefront Threat Management Gateway (TMG) 2010
IDL	Msfpccom.idl
DLL	Msfpccom.dll