Custom User Data

Functions for creating, handling and deleting custom (Add-On specific) User Data attached to specific elements or element groups. More...

Functions
GSErrCode __ACENV_CALL	ACAPI_UserData_GetUserData (API_Attr_Head *attrHead, API_AttributeUserData *userData)
	Obtains the user data attached to an attribute.
GSErrCode __ACENV_CALL	ACAPI_UserData_SetUserData (API_Attr_Head *attrHead, const API_AttributeUserData *userData)
	Attaches user data to an attribute, or deletes the attached data.
GSErrCode __ACENV_CALL	ACAPI_Element_GetUserData (API_Elem_Head *elemHead, API_ElementUserData *userData, UInt32 mask=0)
	Obtains the user data attached to an element or an element default.
GSErrCode __ACENV_CALL	ACAPI_Element_SetUserData (API_Elem_Head *elemHead, const API_ElementUserData *userData)
	Attaches the user data to an element or an element default.
GSErrCode __ACENV_CALL	ACAPI_UserData_DeleteUserData (API_Elem_Head *elemHead)
	Removes the user data attached to the specified element.
GSErrCode __ACENV_CALL	ACAPI_Grouping_GetUserData (const API_Guid &groupGuid, API_UserData *userData)
	Obtains the user data attached to an element group.
GSErrCode __ACENV_CALL	ACAPI_Grouping_SetUserData (const API_Guid &groupGuid, const API_UserData *userData)
	Attaches the user data to the element group.

Detailed Description

Functions for creating, handling and deleting custom (Add-On specific) User Data attached to specific elements or element groups.

Save data into the Element records

This paper give hints on:

• how you can assign additional information to, or
• with other words how you can save own data into

any elements placed onto the floor plan.

Limitations

All Archicad elements can hold extra information (the previous 128-byte limit has been removed in Archicad 8). The registration table is global for the whole project; add-ons are identified by their module ID. It means that one add-on can save the same number of bytes to any kind of element.

Requirements

The structure of the user data is unified for Archicad 8, and it contains the following required fields:

• The version number of the data – this enforces future compatibility.
• The platform where the data was stored.
• And, of course, the data itself, which can contain an arbitrary number of bytes.

Data Structure

The registration table is saved into the project file. Archicad never deletes any registration data. This ensures that your custom data will be preserved, even if your add-on is not installed. It can happen if the user moves a project onto another Archicad installation. If you pass a nullptr handle in the appropriate part of the user data, the custom data will be erased.

The registration itself does not ensure that the data structure of every database element will be extended automatically by the requested number of bytes. These extra bytes are allocated on your request only.

To add your extra bytes to a given element, you should call the ACAPI_Element_SetUserData function, and you can get your data assigned to any element with the ACAPI_Element_GetUserData function. On the parameter list you have to pass an API_ElementUserData structure to store the requested data.

Function Documentation

ACAPI_Element_GetUserData()

GSErrCode __ACENV_CALL ACAPI_Element_GetUserData	(	API_Elem_Head *	elemHead,
		API_ElementUserData *	userData,
		UInt32	mask = 0
	)

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

Parameters

elemHead	[in] Identifies the element or element default (only fields type and guid are used).
userData	[in/out] Pointer to the user data.
mask	[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.

Returns

• 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

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->type 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.

Example

//------------------------------------------------------------
// Obtain user data from wall default element
//------------------------------------------------------------
GSErrCode GetUserDataFromWallDefaultElem (CustomData data)
{
    API_Elem_Head wallDefault = {};
    wallDefault.type = 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;
}

ACAPI_Element_SetUserData()

GSErrCode __ACENV_CALL ACAPI_Element_SetUserData	(	API_Elem_Head *	elemHead,
		const API_ElementUserData *	userData
	)

Attaches the user data to an element or an element default.

Parameters

elemHead	[in] Header of the element (only fields type and guid are used).
userData	[in] Pointer to the new user data.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Any of the passed parameters is nullptr
• APIERR_BADPLATFORMSIGN - The given platform sign is invalid (out of range)
• APIERR_MEMFULL - Out of memory

Remarks

This function is used to push the user attached data into an element default or into an element. To set data to element default only elemHead->type is necessary and elemHead->guid should be APINULLGuid. To set data to an element only elemHead->guid is necessary and it should be set to element's guid. Use the ACAPI_Element_GetUserData function to get data from the element record. Note that this function is not undoable in case of element default setting. The caller should allocate and deallocate the userData->dataHdl handle.

Example

//------------------------------------------------------------
// Set user data to wall default element
//------------------------------------------------------------
 
GSErrCode SetUserDataToWallDefaultElem (const CustomData& data)
{
    API_Elem_Head wallDefault = {};
    wallDefault.type = API_WallID;
 
    API_ElementUserData userData = {};
    userData.dataVersion = 1;
    userData.platformSign = GS::Act_Platform_Sign;
    userData.flags = APIUserDataFlag_FillWith | APIUserDataFlag_Pickup;
    userData.dataHdl = BMAllocateHandle (sizeof (data), ALLOCATE_CLEAR, 0);
 
    *reinterpret_cast<CustomData*> (*userData.dataHdl) = data;
    GSErrCode err = ACAPI_Element_SetUserData (&wallDefault, &userData);
 
    BMKillHandle (&userData.dataHdl);
 
    return err;
}
 
//------------------------------------------------------------
// Set user data to an element identified by guid
//------------------------------------------------------------
 
GSErrCode SetUserDataToElem (const API_Guid& selectedElemGuid, const CustomData& data)
{
    API_Elem_Head element = {};
    element.guid = selectedElemGuid;
 
    API_ElementUserData userData = {};
    userData.dataVersion = 1;
    userData.platformSign = GS::Act_Platform_Sign;
    userData.flags = APIUserDataFlag_FillWith | APIUserDataFlag_Pickup;
    userData.dataHdl = BMAllocateHandle (sizeof (data), ALLOCATE_CLEAR, 0);
 
    *reinterpret_cast<CustomData*> (*userData.dataHdl) = data;
 
    GSErrCode err = ACAPI_CallUndoableCommand ("Set user data to an elem",
        [&userData, &element] () -> GSErrCode {
            return ACAPI_Element_SetUserData (&element, &userData);
        }
    );
 
    BMKillHandle (&userData.dataHdl);
 
    return err;
}

ACAPI_Grouping_GetUserData()

GSErrCode __ACENV_CALL ACAPI_Grouping_GetUserData	(	const API_Guid &	groupGuid,
		API_UserData *	userData
	)

Obtains the user data attached to an element group.

Parameters

groupGuid	[in] Unique ID of the element group.
userData	[in/out] Pointer to the new user data.

Returns

• NoError - The function has completed with success, a new user data has attached to the element group.
• APIERR_NEEDSUNDOSCOPE - The function must be undoable, it wasn't called from an undoable command scope.
• APIERR_BADID - Passed groupGuid ID is invalid.
• APIERR_BADPARS - One or more passed parameters are nullptr.
• APIERR_NOUSERDATA - No user data attached with the gived signature.
• APIERR_MEMFULL - Out of memory.

Remarks

This function is used to get the user attached data from an element group. Use the ACAPI_Grouping_SetUserData functions to push data into the element group.

ACAPI_Grouping_SetUserData()

GSErrCode __ACENV_CALL ACAPI_Grouping_SetUserData	(	const API_Guid &	groupGuid,
		const API_UserData *	userData
	)

Attaches the user data to the element group.

Parameters

groupGuid	[in] Unique ID of the element group.
userData	[in] Pointer to the new user data.

Returns

• NoError - The function has completed with success, a new user data has attached to the element group.
• APIERR_NEEDSUNDOSCOPE - The function must be undoable, it wasn't called from an undoable command scope.
• APIERR_BADID - Passed groupGuid ID is invalid.
• APIERR_BADPARS - Passed groupGuid parameter is nullptr.
• APIERR_BADPLATFORMSIGN - The given platform sign is invalid (out of range).
• APIERR_MEMFULL - Out of memory.

Remarks

This function is used to attach user data to an element group. Use the ACAPI_Grouping_GetUserData function to get data from the element group. Existing user data can be deleted by setting userData input parameter to nullptr. Note that this function is not undoable. The caller should allocate and deallocate the userData->dataHdl handle.

ACAPI_UserData_DeleteUserData()

GSErrCode __ACENV_CALL ACAPI_UserData_DeleteUserData

(

API_Elem_Head *

elemHead

)

Removes the user data attached to the specified element.

Parameters

elemHead

[in] Identifies the element the user data is attached to.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The element does not contain any user data assigned by this add-on.
• APIERR_BADPLATFORMSIGN - The platformsign field in the user data is invalid.
• APIERR_BADID - The passed type is not correct.

Remarks

You can remove the user data that is no longer needed and is attached to an element with this function.

ACAPI_UserData_GetUserData()

GSErrCode __ACENV_CALL ACAPI_UserData_GetUserData	(	API_Attr_Head *	attrHead,
		API_AttributeUserData *	userData
	)

Obtains the user data attached to an attribute.

Since

Archicad 27

Parameters

attrHead	[in] Header of the attribute (only fields typeID and index are used).
userData	[in/out] Pointer to the user data.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Any of the passed parameters is nullptr
• APIERR_BADPLATFORMSIGN - The user data contained platform sign is invalid (out of range)
• APIERR_MEMFULL - Out of memory
• APIERR_NOUSERDATA - No user data attached by the caller module

Remarks

This function is used to get the user attached data from an atribute. The typeID and index fields of the DDD record has to be filled to get the data attached to the attribute. The caller should not allocate the userData->dataHdl field. It's allocated by the function itself but should be destroyed after use by the caller! Use the ACAPI_UserData_SetUserData functions to push data into the attribute record.

ACAPI_UserData_SetUserData()

GSErrCode __ACENV_CALL ACAPI_UserData_SetUserData	(	API_Attr_Head *	attrHead,
		const API_AttributeUserData *	userData
	)

Attaches user data to an attribute, or deletes the attached data.

Parameters

attrHead	[in] The attribute to attach the user data to is defined by the typeID and index fields of the header.
userData	[in] The user data to store. If dataHdl is nullptr, then the function deletes the user data.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - A nullptr attrHead or userData pointer was passed.
• APIERR_BADPLATFORMSIGN - The platform sign in the user data is invalid (out of range).

Remarks

This function is used to attach user data to an an atribute, or to delete the attached information (if userData->dataHdl is nullptr. The caller is responsible for allocating and deleting the userData->dataHdl. You can safely destroy the passed handle after use, as it is copied into the internal database. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.