IFPCSystemPolicyRules2::AddVendorAccessSystemRule method

Article
08/27/2012

Applies to: desktop apps only

The AddVendorAccessSystemRule method creates a new a FPCPolicyRule object representing a vendor-defined system policy rule in the collection and returns a reference to it.

Syntax

HRESULT AddVendorAccessSystemRule(
  [in]   BSTR Name,
  [in]   BSTR RuleGuid,
  [out]  IFPCPolicyRule **ppNewRule
);

FPCSystemPolicyRules.AddVendorAccessSystemRule( _
  ByVal Name As String, _
  ByVal RuleGuid As String, _
  ByRef ppNewRule _
) As FPCPolicyRule

Parameters

Name [in]

C++ Required. BSTR that specifies the name of the new vendor-defined system policy rule.

VB Required. String that specifies the name of the new vendor-defined system policy rule.

RuleGuid [in]

C++	Required. BSTR that specifies the string-formatted globally unique identifier (GUID) of the new vendor-defined system policy rule.
VB	Required. String that specifies the string-formatted globally unique identifier (GUID) of the new vendor-defined system policy rule.

ppNewRule [out]
Address of an interface pointer that on return points to an IFPCPolicyRule interface representing the new vendor-defined system policy rule.

Return value

C++

This method returns 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 the FPCPolicyRule object if the operation is successful. Otherwise, an error is raised that can be intercepted by using an error handler.

Remarks

The GUID supplied in the RuleGuid parameter must be formatted as a string in the form {12345678-1234-1234-1234-123456789abc}. Note the presence of the braces normally used with GUIDs.

This method is available only when the VendorMode property of the FPC (root) object (IFPC2 interface in C++) is set to True (VARIANT_TRUE in C++).

System policy rules cannot be added or deleted in Forefront TMG Management.

Examples

This VBScript script creates a vendor-defined system policy rule with a specific name, GUID, and set of protocols to which it applies for allowing traffic from the LocalHost network to the OEM support site. The hard-coded constants in the script can be modified to create a customized vendor-defined system policy rule.

Option Explicit
'Define the constants needed
Const RuleName = "Allow Access to OEM Support Site"
Const RuleGUID = "{7432DEF8-C451-4C3B-A3AC-AA95C0E5D678}"
Const RuleDesc = "Allows traffic to the OEM support site."
Const UrlSetName = "OEM Support"
Const SupportURL = "http://www.northwindtraders.com"
Const Error_FileNotFound = &H80070002
Const Error_FileAlreadyExits = &H800700B7
Dim selectedProtocols(1)
selectedProtocols(0) = "HTTP"
selectedProtocols(1) = "HTTPS"
AddVendorSystemPolicyRule
Sub AddVendorSystemPolicyRule()
    ' Define enumeration values.
    Const fpcPolicyRuleActionAllow = 0
    Const fpcInclude = 0
    Const fpcSpecifiedProtocols = 1
    ' Create the root object and set the VendorMode property to True.
    Dim root  ' The FPCLib.FPC root object
    Set root = CreateObject("FPC.Root")
    root.VendorMode = True
    'Declare the other objects needed.
    Dim isaArray    ' An FPCArray object
    Dim spRules     ' An FPCSystemPolicyRules collection
    Dim urlSets     ' An FPCURLSets collection
    Dim urlSet      ' An FPCURLSet object
    Dim newRule     ' An FPCPolicyRule object
    Dim i           ' An integer
    ' Get references to the array object, the system policy
    ' rules collection, and the URL sets collection.
    Set isaArray = root.GetContainingArray()
    Set spRules = isaArray.SystemPolicy.PolicyRules
    Set urlSets = isaArray.RuleElements.URLSets
    On Error Resume Next
    Set urlSet = urlSets.Item(UrlSetName)
    If err.Number = Error_FileNotFound Then
        WScript.Echo "Creating the new URL set for the OEM support site ..."
        err.Clear
        Set urlSet = urlSets.Add(UrlSetName)
        CheckError
    Else
        WScript.Echo "The URL set OEM Support already exists."
    End If
    urlSet.Add SupportUrl
    If err.Number = Error_FileAlreadyExists Then
       err.Clear
    Else
        CheckError
    End If
    urlSets.Save
    CheckError
    Set newRule = spRules.Item(RuleName)
    If err.Number = Error_FileNotFound Then
        WScript.Echo "Creating the new system policy rule ..."
        Err.Clear
        Set newRule = spRules.AddVendorAccessSystemRule(RuleName, RuleGUID)
        CheckError
    Else
        WScript.Echo "The " & RuleName & " system policy rule already exists."
        root.VendorMode = False
        WScript.Quit
    End If
    On Error GoTo 0
    ' Specify the description.
    newRule.Description = RuleDesc
    ' Configure the new rule as an allow rule.
    newRule.Action = fpcPolicyRuleActionAllow
    ' Define the source and destination for the new system policy rule.
    newRule.SourceSelectionIPs.Networks.Add "Local Host", fpcInclude
    ' Add the new URL set to the objects referenced by the
    ' URLSets property of the new system policy rule.
    newRule.AccessProperties.URLSets.Add UrlSetName, fpcInclude
    'Set the selected protocols.
    i = 0
    newRule.AccessProperties.ProtocolSelectionMethod = fpcSpecifiedProtocols
    Do
        newRule.AccessProperties.SpecifiedProtocols.Add selectedProtocols(i), fpcInclude
        i = i + 1
    Loop Until i > UBound(selectedProtocols)
    ' Set the user set to which the rule applies.
    newRule.AccessProperties.UserSets.Add "All Users", fpcInclude
    ' Save the changes to the new vendor-defined system policy rule.
    spRules.Save
    root.VendorMode = False
    WScript.Echo "Done!"
End Sub 
Sub CheckError()
    If Err.Number <> 0 Then
        WScript.Echo "An error occurred: 0x" & Hex(Err.Number) & ". " _
            & Err.Description
        Err.Clear
        root.VendorMode = False
        WScript.Quit
    End If
End Sub

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