Returns information on the main parameters of a given element.
GSErrCode ACAPI_Element_Get ( API_Element* element, UInt32 mask );
Parameters
- element
- [in/out] The element participating in the operation.
- mask
- [in] Optional mask. Currently valid values are
0
andAPIElemMask_FloorPlan
. In the latter case, the elements in the floor plan database are counted directly, without changing the database first.
Return Values
NoError
- The function has completed with success.
APIERR_BADPARS
- The passed parameter is
nullptr; element
APIERR_BADID
- The element reference is invalid (
guid
). The element type is invalid, or
the element type is not supported by the server application 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 the main parameters of a given element in the API_Element structure, which is a union of the different element structures.
There is only one way (from API 18 or later) to identify the element:
- pass the
guid
of the element in the element header.
The information returned is the main data of the element; further information can be obtained with the ACAPI_Element_GetMemo function, where applicable; the hasMemo
field of the header indicates the existence of the extra information.
Please use filtering with the ACAPI_Element_Filter function before calling this function; in this case you can spare the conversion time in certain cases.
Please note that the attributes referenced by the element may be invalid. The layer attribute is the only one, which must exist. Other type of attributes my be deleted without editing the element database, it results that elements may refer <MISSING> attributes. In this case the ACAPI_Attribute_Get function returns an error code.
Example
GSErrCode lastErr; API_Element element; GS::Array<API_Guid> columnList; lastErr = ACAPI_Element_GetElemList (API_ColumnID, &columnList, APIFilt_OnVisLayer | APIFilt_OnActFloor); if (lastErr != NoError) return lastErr; for (GS::Array<API_Guid>::ConstIterator it = columnList.Enumerate (); it != nullptr; ++it) { BNZeroMemory (&element, sizeof (API_Element)); element.header.guid = *it; lastErr = ACAPI_Element_Get (&element); if (lastErr == NoError) { /* Custom element processing */ } }
Requirements
- Version: API 1.3 or later
- Header: ACAPinc.h
See Also
API_Elem_Head, API_Element,
ACAPI_Element_GetMemo, ACAPI_Element_Filter,
Element Manager, API Functions