Add Method of the IFPCWebFilters Interface

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

[C++]

Syntax

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

Parameters

Guid
Required. BSTR that specifies the globally unique identifier (GUID) of the new filter.
Name
Required. BSTR that specifies the display name of the new filter.
RelativePath
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\).
Priority

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

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

Address of an interface pointer that on return points to the new IFPCWebFilter interface created.

Return Value

This method can return one of the following:
[Visual Basic]

Syntax

Function Add( _
  ByVal Guid As String, _
  ByVal Name As String, _
  ByVal RelativePath As String, _
  ByVal Priority As FpcFilterPriority, _
  ByVal Direction As FpcFilterDirection _
) As FPCWebFilter

Parameters

Guid
Required. String that specifies the globally unique identifier (GUID) of the new filter.
Name
Required. String that specifies the display name of the new filter.
RelativePath
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

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

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.

Return Value

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.

Example Code

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!"

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.

Requirements

Client Requires Windows Vista or Windows XP.
Server Requires Windows Server 2008.
Version Requires Forefront Threat Management Gateway (TMG).
IDL

Declared in Msfpccom.idl.
DLL

Requires Msfpccom.dll.

See Also

FPCWebFilters


Send comments about this topic to Microsoft

Build date: 11/30/2009

 

© 2008 Microsoft Corporation. All rights reserved.