ACAPI_​Element_​GetMemo

Retrieves all additional information attached to elements.

    GSErrCode  ACAPI_Element_GetMemo (
        const API_Guid&      guid,
        API_ElementMemo*     memo,
        UInt64               mask = APIMemoMask_All
    );

 

Parameters

guid 12
[in] Guid of the element.
memo
[out] Pointer to the memo to be filled.
mask 12
[in] Specifies which part of the memo you are interested in.

 

Return Values

NoError
The function has completed with success.
APIERR_BADPARS
The passed memo parameter is nullptr
APIERR_BADID
The element type is invalid, or
the element type is not supported by the server application
APIERR_BADID
The element guid is invalid.
APIERR_DELETED
The element does not exist in the database
APIERR_MEMFULL
not enough memory to complete the operation

For other common API errors see the API Errors document.

 

Remarks

This function returns additional information attached to elements. This doesn’t apply to all the drawing elements; you can check the hasMemo field of the element header.

The following table shows which elements may have additional data attached; it also explains what information is returned in API_ElementMemo.

Value

Parameters

Function (📝)

API_WallID

(API_Gable **) gables
(API_Coord **) coords
(Int32 **) pends
(API_PolyArc **) parcs
(UInt32 **) vertexIDs
(ProfileVectorImage*) customOrigProfile Featuring API 10
(ProfileVectorImage*) stretchedProfile Featuring API 10
(API_Guid **) wallWindows
(API_Guid **) wallDoors

Returns the gable1 and the polygon data2 and the vector image data of the complex cross-section profile5. May also return the windows and doors in this wall.

API_ColumnID

(API_Gable **) gables
(ProfileVectorImage*) customOrigProfile Featuring API 10
(ProfileVectorImage*) stretchedProfile Featuring API 10
(API_ColumnSegmentType*) columnSegments Featuring API 17
(API_AssemblySegmentCutData*) assemblySegmentCuts Featuring API 17
(API_AssemblySegmentSchemeData*) assemblySegmentSchemes Featuring API 17
(API_AssemblySegmentProfileData*) assemblySegmentProfiles Featuring API 17

Returns the gable data1, the vector image data of the complex cross-section profile5 and segment related information.

API_BeamID

(API_Gable **) gables
(API_Beam_Hole **) beamHoles
(ProfileVectorImage*) customOrigProfile Featuring API 10
(ProfileVectorImage*) stretchedProfile Featuring API 10
(API_BeamSegmentType*) beamSegments Featuring API 17
(API_AssemblySegmentCutData*) assemblySegmentCuts Featuring API 17
(API_AssemblySegmentSchemeData*) assemblySegmentSchemes Featuring API 17
(API_AssemblySegmentProfileData*) assemblySegmentProfiles Featuring API 17

Returns the gable data1, the vector image data of the complex cross-section profile5, the holes of the beam, and segment related information.

API_WindowID
API_DoorID

(API_Gable **) gables
(char **) textContent
(API_AddParType **) params

Returns the gable data1 and the parameters of the instance of a library part4, also the window / door orientation text in textContent.

API_ObjectID
API_LampID

(API_Gable **) gables
(API_AddParType **) params

Returns the gable data1 and the parameters of the instance of a library part4

API_SkylightID Featuring API 15

(API_AddParType **) params

Returns the parameters of the instance of a library part4

API_SlabID

(API_Coord **) coords
(Int32 **) pends
(API_PolyArc **) parcs
(UInt32 **) vertexIDs
(UInt32 **) edgeIDs
(UInt32 **) contourIDs
(API_EdgeTrim **) edgeTrims
(API_OverriddenAttribute *) sideMaterials Featuring API 17

Returns the polygon2, the edge trim data3 and the side materials6 of the slab.

API_RoofID

(API_Coord **) coords
(Int32 **) pends
(API_PolyArc **) parcs
(UInt32 **) vertexIDs
(API_EdgeTrim **) edgeTrims
(API_RoofEdgeTypeID *) roofEdgeTypes
(API_OverriddenAttribute *) sideMaterials Featuring API 17
(API_Coord **) pivotPolyCoords
(Int32 **) pivotPolyPends
(API_PolyArc **) pivotPolyParcs
(UInt32 ** *) pivotPolyVertexIDs
(API_PivotPolyEdgeData *) pivotPolyEdges

  • API_PlaneRoofID: Returns the polygon2, the edge trim data3 and the side materials6 of the roof.
  • API_PolyRoofID: Returns the contour and pivot polygons2, the edge trim data3, the side materials6 and the data of the pivot polygon edges7 of the roof.  Featuring API 15

API_MeshID

(API_Coord **) coords
(Int32 **) pends
(API_PolyArc **) parcs
(UInt32 **) vertexIDs
(double **) meshPolyZ
(API_MeshLevelCoord **) meshLevelCoords
(Int32 **) meshLevelEnds

Returns the polygon2 of the mesh, and the level lines

API_ShellID Featuring API 15

API_ShellShapeData shellShapes[2]
(API_ShellContourData*) shellContours

Returns the profile shape polygon(s)8 and the clipping and hole contour data9 of the shell

API_MorphID Featuring API 16

(Modeler::Body*) morphBody
(API_OverriddenAttribute*) morphMaterialMapTable Featuring API 17

Returns the body and the material override map table of the morph

API_DimensionID

(API_DimElem **) dimElems

Returns the coordinates, the neig information, the text, and the witness line information of the dimension

API_LabelID

(char **) textContent
(short **) textLineStarts
(API_ParagraphType **) paragraphs

(API_AddParType **) params

Returns the text and its style for text-type labels, or the parameters of the originating library part for symbol labels.

API_SplineID

(API_Coord **) coords
(API_SplineDir **) bezierDirs

Returns the Bezier curve parameters

API_TextID

(char **) textContent
(short **) textLineStarts
(API_ParagraphType **) paragraphs

Returns the content the line starts (offsets into textContent) and the style informations of the text. The content can be either in UTF-8 or UTF-16 encoding, depending on the text element’s charCode member and the memo mask.

API_HatchID

(API_Coord **) coords
(Int32 **) pends
(API_PolyArc **) parcs
(UInt32 **) vertexIDs

Returns the polygon of the hatch

API_ZoneID

(API_Gable **) gables
(API_Coord **) coords
(Int32 **) pends
(API_PolyArc **) parcs
(API_AddParType **) params

Returns the polygon of the room2

API_CameraID

(API_LinkType **) linkList

Returns the data of the camera

API_CutPlaneID

(API_Coord **) sectionSegmentMainCoords
(API_Coord **) sectionSegmentDistCoords
(API_Coord **) sectionSegmentDepthCoords

Returns the coordinates of the main, amrked distant area, and depth line of the section segment.

API_ElevationID

(API_Coord **) sectionSegmentMainCoords
(API_Coord **) sectionSegmentDistCoords
(API_Coord **) sectionSegmentDepthCoords

Returns the coordinates of the main, amrked distant area, and depth line of the section segment.

API_InteriorElevationID

(API_SectionSegment **) intElevSegments
(API_Coord **) sectionSegmentMainCoords
(API_Coord **) sectionSegmentDistCoords
(API_Coord **) sectionSegmentDepthCoord
(API_AddParType **) params

Returns the coordinates of the main, amrked distant area, and depth line of the section segment, and also the parameters of the common marker.

API_ChangeMarkerID

(API_Coord **) coords
(Int32 **) pends
(API_PolyArc **) parcs

Returns the polygon of the ChangeMarker2, if it has a polygon.

API_DetailID
API_WorksheetID

(API_Coord **) coords
(Int32 **) pends
(API_PolyArc **) parcs

Returns the polygon of the detail or worksheet2

API_PolyLineID

(API_Coord **) coords
(Int32 **) pends
(API_PolyArc **) parcs

Returns the polygon of the polyline2

API_PictureID

(char **) pictHdl

Returns the picture

API_DrawingID

(API_Coord **) coords
(Int32 **) pends
(API_PolyArc **) parcs
(GSPtr) drawingData Featuring API 10

Returns the polygon and drawing data of a drawing element

API_CurtainWallID 12

(API_Coord **) coords
(Int32 **) pends
(API_PolyArc **) parcs
(UInt32 **) vertexIDs
(API_CWSegmentPatternData) cWSegPrimaryPattern
(API_CWSegmentPatternData) cWSegSecondaryPattern
(API_CWSegmentPatternCellData*) cWSegPatternCells
(API_CWSegmentType*) cWallSegments
(API_CWFrameType*) cWallFrames
(API_CWFrameType*) cWallFrameDefaults
(API_CWPanelType*) cWallPanels
(API_CWPanelGridIDTable*) cWallPanelGridIDTable
(API_CWPanelType*) cWallPanelDefaults
(API_CWPanelType*) cWallPanelDefaultSymbs
(API_CWJunctionType*) cWallJunctions
(API_CWAccessoryType*) cWallAccessories

Returns the polygon and all CW related data.
cWSegPrimaryPattern, cWSegSecondaryPattern and cWSegPatternCells members will contain the default segment scheme of the curtain wall.

API_CurtainWallSegmentID 12

(API_GridMesh*) cWSegGridMesh
(API_CWContourData*) cWSegContour
(API_CWSegmentPatternData) cWSegPrimaryPattern
(API_CWSegmentPatternData) cWSegSecondaryPattern
(API_CWSegmentPatternCellData*) cWSegPatternCells

Returns the CW segment related data.

API_CurtainWallPanelID 12

(API_Coord **) coords

Returns the coordinates of the panel’s polygon. Please note that a curtain wall panel cannot contain holes.

API_StairID 12

(API_StairRiserType*) stairRisers;
(API_StairTreadType*) stairTreads;
(API_StairStructureType*) stairStructures;
(API_StairBoundaryData[2]) stairBoundary;

Returns the Stair related data.

API_RailingID 12

(API_Coord **) coords
(Int32 **) pends
(API_PolyArc **) parcs
(API_RailingNodeType*) railingNodes;
(API_RailingSegmentType*) railingSegments;
(API_RailingPostType*) railingPosts;
(API_RailingRailEndType*) railingRailEnds;
(API_RailingRailEndType*) railingHandrailEnds;
(API_RailingRailEndType*) railingToprailEnds;
(API_RailingRailConnectionType*) railingRailConnections;
(API_RailingRailConnectionType*) railingHandrailConnections;
(API_RailingRailConnectionType*) railingToprailConnections;
(API_RailingRailType*) railingRails;
(API_RailingToprailType*) railingToprails;
(API_RailingHandrailType*) railingHandrails;
(API_RailingPatternType*) railingPatterns;
(API_RailingInnerPostType*) railingInnerPosts;
(API_RailingPanelType*) railingPanels;
(API_RailingBalusterSetType*) railingBalusterSets;
(API_RailingBalusterType*) railingBalusters;
(double**) polyZCoords;

Returns the Railing related data.

1 Any number of gables can be present.
2 See the description of API_Polygon.
3 The length of the API_EdgeTrim memo handle is (poly.nCoords+1)*sizeof(API_EdgeTrim); the first and the last record are not used, filled with zero.
4 The parameters of an element are the parameters of its originating library part, their values are taken from the actual instance.
5 The drawing primitives of the complex profile are stored in a serialized HGX::VectorImage.
6 The length of the sideMaterials memo array is (poly.nCoords+1)*sizeof(API_OverriddenAttribute); the first and the last record are not used, filled with zero.
7 The length of the pivotPolyEdges memo array is (pivotPolygon.nCoords+1)*sizeof(API_PivotPolyEdgeData); the first and the last record are not used, filled with zero.
8 Fixed size array of two API_ShellShapeData records. The members of API_ShellShapeData are handled similarly to the members of API_Polygon.
9 The number of API_ShellContourData records in the shellContours memo array can be calculated from the API_ShellType parameters: numHoles+(hasContour?1:0).

 

12  For improving performance you can select which data is needed with the mask parameter. This feature provides filtered access to the attached data; instead of converting all the attached data, the function returns only those which are in interest.

The possible values of the mask are:

Mask Meaning
APIMemoMask_Polygon Returns the polygon for polygonal elements. For more information see API_Polygon.
APIMemoMask_Gables Returns the gable information.
APIMemoMask_AddPars Returns the additional parameters of a library part-based element (object, lamp, door, window, zone stamp, label).
APIMemoMask_EdgeTrims Featuring API 15 Returns the edge trim information for roofs and slabs. (Renamed from APIMemoMask_RoofSide.)
APIMemoMask_MeshPolyZ Returns Z coordinates of the mesh points for meshes.
APIMemoMask_MeshLevel Returns the mesh level information for meshes.
APIMemoMask_BeamHole Returns the hole information for beams.
APIMemoMask_TextContent Returns the content as ANSI string for textual elements (Text, Label). (This is the default.)
APIMemoMask_Paragraph Returns paragraph informations for textual elements (Text, Label). The paragraphs handle contains byte offsets. Use with APIMemoMask_TextContent mask. (This is the default.)
APIMemoMask_TextContentUni Returns the content as UniCode string for textual elements (Text, Label). You should cast the textContent handle to unsigned short **
APIMemoMask_ParagraphUni Returns paragraph informations for textual elements (Text, Label). The paragraphs handle contains character offsets. Use with APIMemoMask_TextContentUni mask.
APIMemoMask_DrawingData  Featuring API 10 Returns the drawing data of a drawing element (API_DrawingType) in internal format. See also APIDb_StopDrawingDataID.
APIMemoMask_CustomOrigProfile  Featuring API 10 Returns the original custom profile data applied to the wall, beam, or column element.
APIMemoMask_StretchedProfile  Featuring API 10 Returns the stretched profile actually used by the wall, beam, or column element.
APIMemoMask_SectionSegments  Featuring API 11 Returns the section segments of a section, elevation, or interior elevation element.
APIMemoMask_SectionMainCoords  Featuring API 21 Returns the section view line coordinates of a section, elevation, or interior elevation element.
APIMemoMask_SectionDistCoords  Featuring API 21 Returns the section marked distant area line coordinates of a section, elevation, or interior elevation element.
APIMemoMask_SectionDepthCoords  Featuring API 21 Returns the section depth line coordinates of a section, elevation, or interior elevation element.
APIMemoMask_WallWindows  12 Returns the Guid list of the windows placed in a given wall element.
APIMemoMask_WallDoors  12 Returns the Guid list of the doors placed in a given wall element.
APIMemoMask_CWSegGridMesh  12 Returns the GridMesh of a curtain wall segment.
APIMemoMask_CWSegPrimaryPattern  12 Returns the primary pattern of a curtain wall segment.
APIMemoMask_CWSegSecPattern  12 Returns the secondary pattern of a curtain wall segment.
APIMemoMask_CWSegPanelPattern  12 Returns the panel pattern of curtain wall segment.
APIMemoMask_CWSegContour  12 Returns the contour of curtain wall segment.
APIMemoMask_CWallSegments  12 Returns the segments of curtain wall element.
APIMemoMask_CWallFrames  12 Returns the frames of curtain wall element.
APIMemoMask_CWallPanels  12 Returns the panels of curtain wall element.
APIMemoMask_CWallJunctions  12 Returns the junctions of curtain wall element.
APIMemoMask_CWallAccessories  12 Returns the accessories of curtain wall element.
APIMemoMask_FromFloorPlan Featuring API 12 Additional flag; take the element information from the floor plan database. This flag is excluded from APIMemoMask_All!
APIMemoMask_RoofEdgeTypes  13 Returns the edge types of the contour polygon of a roof element.
APIMemoMask_SideMaterials  13 Returns the side material indices of a Slab or Roof element.
APIMemoMask_PivotPolygon  Featuring API 15 Returns the pivot polygon and the pivot edges of a Multi-plane Roof element (see API_PolyRoofData).
APIMemoMask_StairRiser  Featuring API 21 Returns the Riser subelements of a Stair element.
APIMemoMask_StairTread  Featuring API 21 Returns the Tread subelements of a Stair element.
APIMemoMask_StairStructure  Featuring API 21 Returns the Stair Structure subelements of a Stair element.
APIMemoMask_RailingNode  Featuring API 21 Returns the Nodes of a Railing element.
APIMemoMask_RailingSegment  Featuring API 21 Returns the Segments of a Railing element.
APIMemoMask_RailingPost  Featuring API 21 Returns the Railing Posts of a Railing element.
APIMemoMask_RailingInnerPost  Featuring API 21 Returns the Inner Posts of a Railing element.
APIMemoMask_RailingRail  Featuring API 21 Returns the Rails of a Railing element.
APIMemoMask_RailingHandrail  Featuring API 21 Returns the Handrails of a Railing element.
APIMemoMask_RailingToprail  Featuring API 21 Returns the Toprails of a Railing element.
APIMemoMask_RailingPanel  Featuring API 21 Returns the Railing Panels of a Railing element.
APIMemoMask_RailingBaluster  Featuring API 21 Returns the Balusters of a Railing element.
APIMemoMask_RailingPattern  Featuring API 21 Returns the Railing Patterns of a Railing element.
APIMemoMask_RailingBalusterSet  Featuring API 21 Returns the Baluster Sets of a Railing element.
APIMemoMask_RailingRailEnd  Featuring API 21 Returns the Rail Ends of a Railing Node element.
APIMemoMask_RailingRailConnection  Featuring API 21 Returns the Rail Connections of a Railing Node element.
APIMemoMask_BeamSegment  Featuring API 23 Returns the Beam segments of a Beam element.
APIMemoMask_ColumnSegment  Featuring API 23 Returns the Column segments of a Column element.
APIMemoMask_AssemblySegmentCut  Featuring API 23 Returns cuts of a Column or a Beam element.
APIMemoMask_AssemblySegmentScheme  Featuring API 23 Returns schemes of ColumnSegments or BeamSegments.
APIMemoMask_AssemblySegmentProfile  Featuring API 23 Returns profiles of ColumnSegments or BeamSegments.
APIMemoMask_SurfaceLoadCustomData  Featuring API 25 Returns the contour of the Custom Surface Load
APIMemoMask_All Returns all the applicable fields for the element.

Do not forget to call ACAPI_DisposeElemMemoHdls to dispose of the handles when you’re finished.

Example


void DoAnything (const API_Guid&)
{
    API_Element      element = {};
    API_ElementMemo  memo;
    GSErrCode        err;

    element.header.guid = guid;
    err = ACAPI_Element_Get (&element);

    if (err == NoError && element.header.hasMemo) {
        err = ACAPI_Element_GetMemo (element.header.guid, &memo, APIMemoMask_Gables);
        if (err == NoError) {
            /* ... do anything with it ... */
        }
        ACAPI_DisposeElemMemoHdls (&memo);
    }
}

 

Requirements

Version: API 1.3 or later
Header: ACAPinc.h

 

See Also

API_ElemTypeID, API_Polygon, API_ElementMemo
ACAPI_DisposeElemMemoHdls
Element Manager, API Functions