ACAPI_​Element_​GetRelations

Returns information on objects connected to walls, beams, beam segments, rooms, shells, roofs, curtain wall panels, skylights, windows and doors.

    GSErrCode  ACAPI_Element_GetRelations (
        const API_Guid&      guid,
        const API_ElemType&  otherType,
        void*                relData,
        UInt32               mask = 0
    );

 

Parameters

guid 12
[in] Guid of the element.
otherType
[in] Type of the requested element.
relData
[out] The relation data returned by the function. This pointer must refer to an API_WallRelation, API_BeamRelation, API_BeamSegmentRelation, API_RoomRelation, API_RoofRelation, API_ShellRelation, API_CWPanelRelation, API_SkylightRelation, API_WindowRelation, or an API_DoorRelation structure according to the type of the requested element given be the guid parameter.
mask New in API 22
[in] Optional mask. Currently valid values are 0 and APIElemMask_FromFloorplan. In the latter case, the element referred by guid is searched in the floor plan database.

 

Return Values

NoError
The operation was successful.
APIERR_BADPARS
The relData parameter was nullptr or otherID parameter is incorrect.
APIERR_BADID
Incorrect guid was specified.
APIERR_DELETED
The element does not exist in the database

For other common API errors see the API Errors document.

 

Remarks

This function returns information on elements connected to the element identified by the given guid. The requested object type is given in otherType.

Type of the given element

otherID

Comment

walls

API_ZombieElemID, API_WallID

For walls the connected elements and the modified polygon is put into relData. Positive indices mean that the begin point of the other object is connected to the wall; while negative indices mean the end point. Five types of connections are returned: walls which are connected to the begin point, to the end point and to the reference line of the wall, walls to the reference line of whose the wall you requested information on is connected, and cross connections.

rooms

API_ZombieElemID, API_WallID, API_ColumnID, API_ObjectID, API_LampID, API_WindowID API_DoorID, API_BeamID, API_CurtainWallID, API_CurtainWallFrameID, API_CurtainWallPanelID, API_CurtainWallJunctionID, API_CurtainWallAccessoryID, API_CurtainWallSegmentID, API_SkylightID, API_RoofID, API_ShellID, API_MorphID, API_StairID, API_RiserID, API_TreadID, API_StairStructureID, API_RailingID, API_RailingToprailID, API_RailingHandrailID, API_RailingRailID, API_RailingPostID, API_RailingInnerPostID, API_RailingBalusterID, API_RailingPanelID, API_RailingSegmentID, API_RailingToprailEndID, API_RailingHandrailEndID, API_RailingRailEndID, API_RailingToprailConnectionID, API_RailingHandrailConnectionID, API_RailingRailConnectionID, API_RailingNodeID or API_SlabID

For rooms, the walls, columns, objects, lamps, windows, doors, beams, curtain walls, skylights, roofs, shells, morphs, stairs, risers, treads, railings and slabs are returned. For walls, beams and curtain wall segments the returned information contains that segment of the wall which is inside the room (see API_WallPart/API_CWSegmentPart and API_BeamPart). 24

beams

API_ZombieElemID or API_BeamID

For beams the connected elements and the modified polygon is put into relData. Positive indices mean that the begin point of the other object is connected to the beam; while negative indices mean the end point. Five types of connections are returned: beams which are connected to the begin point, to the end point and to the reference line of the beam, beams to the reference line of whose the beam you requested information on is connected, and cross connections.

beam segments

API_ZombieElemID or API_BeamSegmentID

For beam segments the connected elements and the modified polygon is put into relData. Positive indices mean that the begin point of the other object is connected to the beam segment; while negative indices mean the end point. Five types of connections are returned: beam segments which are connected to the begin point, to the end point and to the reference line of the beam segment, beam segments to the reference line of whose the beam segment you requested information on is connected, and cross connections.

curtain wall panels and skylights

API_ZombieElemID or API_ZoneID

For curtain wall panels and skylights the connected rooms are put into relData.  Featuring API 12

windows and doors

API_ZombieElemID or API_ZoneID

For windows and doors the connected rooms are put into relData.  Featuring API 19

roof and shell

API_ZombieElemID or API_ZoneID

For roof and shell the connected rooms are put into rooms.  Featuring API 15

Don’t forget to call the appropriate ACAPI_DisposeRoomRelationHdls, ACAPI_DisposeWallRelationHdls, ACAPI_DisposeBeamRelationHdls, or ACAPI_DisposeBeamSegmentRelationHdls function to dispose the handles.

New in API 26 From version 26 the otherTypeID parameter was changed into an API_ElemType parameter.

 

Example


// API_WallRelation example
API_WallRelation            relData;
GS::Array<API_Guid>	    elemList;

ACAPI_Element_GetElemList (API_WallID, &elemList);
for (const API_Guid& wallGuid : elemList) {
    if (ACAPI_Element_GetRelations (wallGuid, API_WallID, (void*)& relData) != NoError)
        continue;

    ACAPI_WriteReport ("Connected walls to the wall %s", false, APIGuidToString (wallGuid).ToCStr ().Get ());

    if (relData.conBeg != nullptr) {
        ACAPI_WriteReport ("\tat the begin point:", false);
        for (Int32 ind = 0; ind < relData.nConBeg; ind++) {
            ACAPI_WriteReport ("\t\t#%ld ", false, (*(relData.conBeg))[ind]);
        }
    }

    if (relData.conEnd != nullptr) {
        ACAPI_WriteReport ("\tat the end point:", false);
        for (Int32 ind = 0; ind < relData.nConEnd; ind++) {
            ACAPI_WriteReport ("\t\t#%d", false, (*(relData.conEnd))[ind]);
        }
    }

    if (relData.conRef != nullptr) {
        ACAPI_WriteReport ("\ton the reference line not at the end points:", false);
        for (Int32 ind = 0; ind < relData.nConRef; ind++) {
            ACAPI_WriteReport ("\t\t#%d", false, (*(relData.conRef))[ind]);
        }
    }

    if (relData.con != nullptr) {
        ACAPI_WriteReport ("\ton the reference line:", false);
        for (Int32 ind = 0; ind < relData.nCon; ind++) {
            ACAPI_WriteReport ("\t\t#%d", false, (*(relData.con))[ind]);
        }
    }

    if (relData.conX != nullptr) {
        ACAPI_WriteReport ("\thaving intersection with:", false);
        for (Int32 ind = 0; ind < relData.nConX; ind++) {
            ACAPI_WriteReport ("\t\t#%d", false, (*(relData.conX))[ind]);
        }
    }

    ACAPI_DisposeWallRelationHdls (&relData);
}

// API_RoomRelation example
API_RoomRelation            roomData;

elemList = {};
ACAPI_Element_GetElemList (API_ZoneID, &elemList);
for (const API_Guid& roomGuid : elemList) {
    if (ACAPI_Element_GetRelations (roomGuid, API_ZombieElemID, (void*)& roomData) != NoError)
        continue;
    ACAPI_WriteReport ("Connected elems to the room %s", false, APIGuidToString (roomGuid).ToCStr ().Get ());

    ACAPI_WriteReport ("\tWalls:", false);
    if (roomData.relatedElementsGroupedByType.ContainsKey (API_WallID)) {
        for (const API_Guid& wallGuid : roomData.relatedElementsGroupedByType[API_WallID]) {
            ACAPI_WriteReport ("\t\t%s", false, APIGuidToString (wallGuid).ToCStr ().Get ());
        }
    }

    ACAPI_WriteReport ("\tSlabs:", false);
    if (roomData.relatedElementsGroupedByType.ContainsKey (API_SlabID)) {
        for (const API_Guid& slabGuid : roomData.relatedElementsGroupedByType[API_SlabID]) {
            ACAPI_WriteReport ("\t\t%s", false, APIGuidToString (slabGuid).ToCStr ().Get ());
        }
    }

    ACAPI_DisposeRoomRelationHdls (&roomData);
}

 

Requirements

Version: API 1.3 or later
Header: ACAPinc.h

 

See Also

API_Guid, API_ElemTypeID, API_WallRelation, API_BeamRelation, API_BeamSegmentRelation, API_RoomRelation, API_CWPanelRelation, API_SkylightRelation, API_ShellRelation, API_RoofRelation, API_WallPart, API_BeamPart, API_Niche,
ACAPI_DisposeRoomRelationHdls, ACAPI_DisposeWallRelationHdls, ACAPI_DisposeBeamRelationHdls, ACAPI_DisposeBeamSegmentRelationHdls,
Element Relations, Element Manager, API Functions