IFPC::GetContainingArray method

Article
08/27/2012

Applies to: desktop apps only

The GetContainingArray method retrieves the FPCArray object (IFPCArray interface in C++) that represents the array containing the current computer.

Note This method is only relevant when executed on a computer which runs the Microsoft Firewall service.

Syntax

HRESULT GetContainingArray(
  [out]  IFPCArray **ppItem
);

FPC.GetContainingArray( _
  ByRef ppItem As IFPCArray _
) As FPCArray

Parameters

ppItem [out]
Address of an interface pointer that on return points to the IFPCArray interface that represents the containing array.

Return value

C++

This method can return one of the following:

S_OK, indicating that the operation succeeded.
ERROR_FILE_NOT_FOUND, indicating that the IFPCArray interface could not be found because the method was called on a remote management computer or a Configuration Storage server on which the Microsoft Firewall service is not installed. In this case, the [out] parameter returned is a null object.
E_FPC_NOT_CONNECTED_TO_ENTERPRISE, indicating that the method was called on a remote Forefront TMG management computer that does not have the Firewall service installed and has not been connected to a Configuration Storage server, or that the user (for example, a user logged on as a local administrator) does not have the permissions needed to access information stored on the remote Configuration Storage server. In this case, the [out] parameter returned is a null object.
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 an FPCArray object if successful. Otherwise, an error is raised that can be intercepted by using an error handler. In particular, the following errors may be raised:

ERROR_FILE_NOT_FOUND, indicating that the FPCArray object could not be found because the method was called on a remote management computer or a Configuration Storage server on which the Microsoft Firewall service is not installed.
E_FPC_NOT_CONNECTED_TO_ENTERPRISE, indicating that the method was called on a remote Forefront TMG management computer that does not have the Firewall service installed and has not been connected to a Configuration Storage server, or that the user (for example, a user logged on as a local administrator) does not have the permissions needed to access information stored on the remote Configuration Storage server.

Remarks

This method cannot be used to retrieve an FPCArray object on a remote management computer. For information about retrieving an FPCArray object on a remote management computer, see Retrieving an Array Object.

When this method is called for remote management, it should be called only on a computer that is connected to a Configuration Storage server by a user who has the permissions needed to access information stored on the Configuration Storage server. A computer can be connected to a Configuration Storage server by calling ConnectToConfigurationStorageServer with a valid user name and password before calling this method. This method can also be used to supply valid user credentials for accessing information about the Configuration Storage server.

This method supports multiple arrays (available only in Forefront TMG Enterprise Edition). Assume, for example, that there are two arrays, Array1 and Array2. Array1 contains two computers, A and B. Array2 contains computer C. If you call GetContainingArray on computer A, the method returns Array1. If you call GetContainingArray on computer C, the method returns Array2.

Examples

The following Visual Basic code example retrieves the name of the array containing the current computer by means of the GetContainingArray method.

Dim root As New FPCLib.FPC
Dim arrayName As String
arrayName = root.GetContainingArray.Name

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