Returns a list of elements connected to the given element.

    GSErrCode  ACAPI_Element_GetConnectedElements (
        const API_Guid&          guid,
        const API_ElemType&      connectedElemType,
        GS::Array<API_Guid>*     connectedElements,
        API_ElemFilterFlags      filterBits           = APIFilt_None,
        const API_Guid&          renovationFilterGuid = APINULLGuid
    );

 

Parameters

guid

[in] Identifier of the element having other elements connected to it.

connectedElemType

[in] The type of the connected elements to be retrieved. Currently applicable types: API_WindowID, API_DoorID (with Wall elements), API_SkylightID (with Roof and Shell elements), API_LabelID (with all labelable elements, i.e. modeling elements, Curtain Wall subelements, and Fill elements), API_OpeningID  (with Wall, Slab, Mesh and Beam elements),

connectedElements

[out] Guid list of the connected elements retrieved.

filterBits

[in] The flags used for filtering (see ACAPI_Element_Filter). The default value is APIFilt_None.

renovationFilterGuid 

[in] Optional global unique identifier of the renovation filter. This parameter is currently ignored.

 

Return Values

NoError

The function has completed with success.

APIERR_BADPARS

The connectedElements pointer is nullptr.

APIERR_BADID

The guid parameter does not identify a valid element. Or the given element type cannot be in connection with elements of the requested type.

 

Remarks

This function can be used to get the elements of the given type and variation, that are connected in an ownership relation with a given element, and match the criteria defined by filterbits (see the filterbits flag values described in the table of ACAPI_Element_Filter).

Available connections:

Type of the owner element (specified with guid)	Connected element type (connectedElemTypeID)
API_WallID	API_WindowID, API_DoorID
API_RoofID, API_ShellID	API_SkylightID
All labelable elements	API_LabelID
API_OpeningID	API_WallID, API_SlabID, API_MeshID, API_BeamID

The windows and doors of a given wall element can also be retrieved with the ACAPI_Element_GetMemo function (wallWindows, wallDoors members of API_ElementMemo).

When querying the Labels of an element, if the returned GUID array is not empty, the first GUID will be the GUID of the “Listing Label”. It is the Label, which can be listed in Interactive Schedule.

From version 26 the connectedElemTypeID and variationID parameters were merged into a single API_ElemType parameter.

 

Example

// list Skylights of the Shell elements

GS::Array<API_Guid> shells;
GSErrCode err = ACAPI_Element_GetElemList (API_ShellID, &shells);
if (err == NoError) {
    GS::UniString reportString;
    for (GS::Array<API_Guid>::ConstIterator it = shells.Enumerate (); it != nullptr; ++it) {
        API_Guid shellGuid = *it;
        GS::UniString shellGuidString = APIGuid2GSGuid (shellGuid).ToUniString ();
        GS::Array<API_Guid> skylights;
        err = ACAPI_Element_GetConnectedElements (shellGuid, API_SkylightID, &skylights);
        if (err == NoError) {
            if (skylights.IsEmpty ()) {
                reportString = GS::UniString::Printf ("Shell {%T} has no Skylights", shellGuidString.ToPrintf ());
            } else {
                reportString = GS::UniString::Printf ("Skylights in Shell {%T}:", shellGuidString.ToPrintf ());
                for (UIndex i = 0; i < skylights.GetSize (); i++) {
                    API_Element element;
                    BNZeroMemory (&element, sizeof (API_Element));
                    element.header.guid = skylights[i];
                    if (ACAPI_Element_Get (&element) == NoError) {
                        API_LibPart libPart;
                        BNZeroMemory (&libPart, sizeof (API_LibPart));
                        libPart.index = element.skylight.openingBase.libInd;
                        if (ACAPI_LibPart_Get (&libPart) == NoError) {
                            reportString.Append (" \"");
                            reportString.Append (libPart.docu_UName);
                            reportString.Append ("\"");
                        }
                        delete libPart.location;
                    }
                }
            }
        } else {
            reportString = GS::UniString::Printf ("Failed to get Skylights for Shell {%T}", shellGuidString.ToPrintf ());
        }
        ACAPI_WriteReport (reportString.ToCStr ().Get (), false);
    }
}

 

Requirements

Version: API 15 or later

Header: ACAPinc.h

 

See Also

ACAPI_Element_Filter, ACAPI_Element_GetElemList, ACAPI_Element_GetMemo
Element Manager, API Functions