GetContainingArray Method of the IFPC Interface

  • Article

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.

C++

Syntax

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

Parameters

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

Return Value

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.

Visual Basic

Syntax

Function GetContainingArray() As FPCArray

Parameters

This method has no parameters.

Return Value

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.

Example Code

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

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.

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

FPC

Send comments about this topic to Microsoft

Build date: 6/30/2010