AddVendorAccessSystemRule Method of the IFPCSystemPolicyRules2 Interface

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.
S

C++

Syntax

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

Parameters

• Name
  Required. BSTR that specifies the name of the new vendor-defined system policy rule.

• RuleGuid
  Required. BSTR that specifies the string-formatted globally unique identifier (GUID) of the new vendor-defined system policy rule.

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

Return Value

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.

Visual Basic

Syntax

Function AddVendorAccessSystemRule( _
  ByVal Name As String, _
  ByVal RuleGuid As String _
) As FPCPolicyRule

Parameters

• Name
  Required. String that specifies the name of the new vendor-defined system policy rule.
• RuleGuid
  Required. String that specifies the string-formatted globally unique identifier (GUID) of the new vendor-defined system policy rule.

Return Value

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.

Example Code

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 = "https://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

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.

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

FPCSystemPolicyRules

Send comments about this topic to Microsoft

Build date: 6/30/2010