AddOnObject Manager

The AddOnData Manager is a service introduced in API v19.

It allows each add-on to store custom data in Archicad project database. No limitation is imposed on the structure or content, not even on the amount of saved bytes. Archicad knows nothing about its internal format, it just preserves a number of bytes in the project database and returns them upon requests.

The container of the stored data is an object called AddOnObject. This data structure has a GUID and a name. The name is optional.

AddOnobjects are identified uniquely by the GUID of the object.

 

Unique AddOnObjects  API 21 feature

Unique AddOnObjects were introduced to support more restricted but safer TeamWork behaviour. Because multiple general (non-unique) AddOnObjects can exist with the same name, in TeamWork it could happen that two users created “the same” AddOnObject simultaneously, but at the end they ended up with two different AddOnObjects (with the same name). This led to a lot of confusion.

With Unique AddOnObjects – like general AddOnObjects – you can store custom data in the project database. However – unlike general AddOnObjects – their names must be and will be unique among each other. Please note that names of a Unique AddOnObject and general AddOnObjects may still be equal.

In a TeamWork project creating Unique AddOnObjects will result in a Full Send to ensure project consistency. Due to this inconvenience, it is possible to create more Unique AddOnObjects at once with the ACAPI_AddOnObject_CreateUniqueObjectMore function.

All functions that work for general AddOnObjects work for Unique AddOnObjects, too, except ACAPI_AddOnObject_GetObjectGuidFromName: to get the GUID of a Unique AddOnObject from its name use ACAPI_AddOnObject_GetUniqueObjectGuidFromName instead.

 

Functions

All of the ModulData Manager functions begin with the ACAPI_AddOnObject_ prefix. They are as follows:

ACAPI_AddOnObject_CreateObject
ACAPI_AddOnObject_CreateClientOnlyObject  API 23 feature
ACAPI_AddOnObject_CreateUniqueObject  API 21 feature
ACAPI_AddOnObject_CreateUniqueObjectMore  API 21 feature
ACAPI_AddOnObject_ModifyObject
ACAPI_AddOnObject_DeleteObject
ACAPI_AddOnObject_GetObjectList
ACAPI_AddOnObject_GetObjectContent
ACAPI_AddOnObject_GetObjectGuidFromName
ACAPI_AddOnObject_GetClientOnlyObjectGuidFromName  API 23 feature
ACAPI_AddOnObject_GetUniqueObjectGuidFromName  API 21 feature
ACAPI_AddOnObject_ExistsObject
ACAPI_AddOnObject_ReserveObjects
ACAPI_AddOnObject_ReleaseObjects
ACAPI_AddOnObject_RequestObjects
ACAPI_AddOnObject_GrantObjects
ACAPI_AddOnObject_GetTeamworkOwnerId
ACAPI_AddOnObject_SetUIProperties

Refer to the AddOnObject Manager example project to see detailed examples on using these functions.

 

Merging AddOnObjects

When merging another plan into the project, it might be necessary to keep both the original and the incoming objects, and to combine them together. Since the host application does not know the content of the objects, the owner add-on is requested to resolve the conflict.

For this purpose the add-on needs to implement an APIAddOnObjectMergeHandlerProc callback handler function, and pass the function pointer to Archicad with the ACAPI_Install_AddOnObjectMergeHandler in the Initialize routine. It is also necessary to inform Archicad that the add-on is prepared for merging custom data: this can be done with the ACAPI_Register_AddOnObjectHandler function called from RegisterInterface.

In Teamwork mode the AddOnObject can only be modified by the owner of the object. The add-on can reserve or release one or more AddOnObject using ACAPI_AddOnObject_ReserveObjects and ACAPI_AddOnObject_ReleaseObjects. Only one user can modifiy an object at one time, so no conflict resolution is needed.

 

 Saving data into old format project

If the structure of the custom data has changed since the previous version, you need to implement an APIAddonObjectSaveOldFormatHandlerProc callback function to be able to convert your data when saving into an older format project. In order to be called this handler, the function pointer must be passed with ACAPI_Install_AddOnObjectSaveOldFormatHandler, and the data handling feature must be registered with ACAPI_Register_AddOnObjectHandler.

When Archicad calls this function, the add-on should create the converted data according to the given plan file format, and pass it back to the application.

If the add-on does not install this converter callback routine, the available current format data is saved into the old version project as well.

 

 Converting data when reading an old format project

If the structure of the custom data has changed since the older versions, you need to implement an APIAddonObjectConvertNewFormatHandlerProc callback function to be able to convert your data when opening an older format project. In order to be called this handler, the function pointer must be passed with ACAPI_Install_AddOnObjectConvertNewFormatHandler, and registration with ACAPI_Register_AddOnObjectHandler is also needed.

When Archicad calls this function, the add-on should create the current version data, and pass it back to the application.

If the add-on does not install this converter callback routine, the available orignal format data will be kept in the current version project as well.