_NewEnum Property of the IFPCRefs Interface

Article
08/13/2010

The _NewEnum property gets an enumerator object for the collection. An enumerator object provides serial access to the elements of the collection.

C++

HRESULT get__NewEnum(
    IUnknown* ppEnum
);

Parameters

ppEnum
Address of an interface pointer that on return points to the IUnknown interface of an enumerator object that implements an IEnumVARIANT interface for the collection. An interface pointer to the IEnumVARIANT interface of the enumerator object can be retrieved by calling QueryInterface on the IUnknown interface returned.

Return Value

This property method returns S_OK if the call is successful; otherwise, it returns an error code.

Visual Basic

Property _NewEnum As IUnknown

Property Value

Reference to an enumerator object that provides serial access to the elements of the collection.

Example Code

This VBScript subprocedure retrieves the FPCPolicyRule object representing a specified access rule that is defined in the containing Forefront TMG array. If the access rule applies only to certain protocols or to all IP traffic except certain protocols, the subprocedure retrieves the FPCRefs collection accessed through the SpecifiedProtocols property for the access rule and implicitly uses the _NewEnum property to iterate through the collection display the name of each protocol to which the rule applies or each protocol that is excluded from the access rule. It does not include complete error handling.

Sub IterateSpecifiedProtocols(ruleName)
    ' Define the constants needed.
    Const fpcPolicyRuleAccess = 0
    Const fpcAllIpTraffic = 0
    Const fpcSpecifiedProtocols = 1
    ' Create the root object.
    Set root = CreateObject("FPC.Root")
    ' Declare the other objects needed.
    Dim isaArray       ' An FPCArray object
    Dim rule           ' An FPCPolicyRule object
    Dim references     ' An FPCRefs collection
    Dim reference      ' An FPCRef object
    ' Get references to the array object and the
    ' specified access rule.
    Set isaArray = root.GetContainingArray()
    Set rule = isaArray.ArrayPolicy.PolicyRules.Item(ruleName)
    If rule.Type <> fpcPolicyRuleAccess Then
        WScript.Echo "The " & ruleName & " policy rule is not an access rule."
        WScript.Quit
    End If
    ' Inform the user that the rule applies to all protocols or get
    ' a reference to the collection of references to the specified protocols.
    If rule.AccessProperties.ProtocolSelectionMethod = fpcAllIpTraffic Then
        WScript.Echo "The " & ruleName & " access rule applies to all protocols."
    Else
        Set references = rule.AccessProperties.SpecifiedProtocols
        ' Display the names of the protocols to which the rule applies
        ' or the protocols that are excluded from the rule.
        If rule.AccessProperties.ProtocolSelectionMethod = fpcSpecifiedProtocols Then
            WScript.Echo "The " & ruleName & " access rule applies to the following protocols:"
            For Each reference In references
                WScript.Echo "    " & reference.Name 
            Next
        Else  
            WScript.Echo "The following protocols are excluded from the " & ruleName & " access rule:"
            For Each reference In references
                WScript.Echo "    " & reference.Name 
            Next
        End If
    End If
End Sub

Remarks

This property is read-only.

In Visual Basic and VBScript, this property is used implicitly in For Each...In...Next constructs.

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.

Share via