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