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:
- 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.
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 7 or Windows Vista. |
| Server | Requires Windows Server 2008 R2 or Windows Server 2008 x64 Edition with SP2. |
| Version | Requires Forefront Threat Management Gateway (TMG) 2010. |
| IDL | Declared in Msfpccom.idl. |
| DLL | Requires Msfpccom.dll. |
See Also
Send comments about this topic to Microsoft
Build date: 6/30/2010