ACAPI_​Element_​GetUserData

Obtains the user data attached to an element or an element default.

    GSErrCode  ACAPI_Element_GetUserData (
        API_Elem_Head*           elemHead,
        API_ElementUserData*     userData,
        UInt32                   mask
    );

 

Parameters

elemHead
[in] Identifies the element or element default (only fields typeID and guid are used).
userData
[in/out] Pointer to the user data.
mask Featuring API 12
[in] Optional mask. Currently valid values are 0 and APIElemMask_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; userData
APIERR_BADID
The elemHead is incorrect.
APIERR_NOUSERDATA
No user data attached with the gived signature

For other common API errors see the API Errors document.

 

Remarks

This function is used to get the user attached data from an element or from an element default. To obtain data from element default only elemHead->typeID is necessary and elemHead->guid should be APINULLGuid. To obtain data from an element only elemHead->guid is necessary and it should be set to element’s guid. Use the ACAPI_Element_SetUserData functions to push data into the element record.

You can read more about this topic at the Save data into Element records paper.

 



//------------------------------------------------------------
// Obtain user data from wall default element
//------------------------------------------------------------

GSErrCode GetUserDataFromWallDefaultElem (CustomData& data)
{
    API_Elem_Head wallDefault = {};
    wallDefault.typeID = API_WallID;

    API_ElementUserData userData = {};
    GSErrCode err = ACAPI_Element_GetUserData (&wallDefault, &userData);

    if (err == NoError && userData.dataHdl != nullptr && userData.platformSign == GS::Act_Platform_Sign)
        data = *reinterpret_cast<CustomData*> (*userData.dataHdl);

    BMKillHandle (&userData.dataHdl);

    return NoError;
}

//------------------------------------------------------------
// Obtain user data from an element identified by guid
//------------------------------------------------------------

GSErrCode GetUserDataFromElem (const API_Guid& selectedElemGuid, CustomData& data)
{
    API_Elem_Head element = {};
    element.guid = selectedElemGuid;

    API_ElementUserData userData = {};
    GSErrCode err = ACAPI_Element_GetUserData (&element, &userData);

    if (err == NoError && userData.dataHdl != nullptr && userData.platformSign == GS::Act_Platform_Sign)
        data = *reinterpret_cast<CustomData*> (*userData.dataHdl);

    BMKillHandle (&userData.dataHdl);

    return NoError;
}

        

 

Requirements

Version: API 4.1 or later
Header: ACAPinc.h

 

See Also

API_ElemTypeID, API_ElementUserData,
ACAPI_Element_SetUserData,
Element Manager, API Functions