The ModulData Manager is a very powerful service introduced in API v3.1.
It allows each add-on to own custom data sections in Archicad project files. 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 file and returns them upon requests.
Data sections are identified uniquely by the add-on’s modul ID (‘MDID’) and an optional modul name string. This means the one data per add-on limitation of previous versions has been dissolved.
Functions
All of the ModulData Manager functions begin with the ACAPI_ModulData_ prefix. They are as follows:
ACAPI_ModulData_Store
ACAPI_ModulData_GetInfo
ACAPI_ModulData_Get
ACAPI_ModulData_GetList
ACAPI_ModulData_Delete
Refer to the ModulData Manager example project to see detailed examples on using these functions.
Merging custom data sections
In certain situations modules of the same add-on can conflict with each other. When merging another plan into the project, it might be necessary to keep both the original and the incoming modul data, and to combine them together. Since the host application does not know the content of the modules, the owner add-on is requested to resolve the conflict.
For this purpose the add-on needs to implement an APIModulDataMergeHandlerProc callback handler function, and pass the function pointer to Archicad with the ACAPI_Install_ModulDataMergeHandler in the Initialize routine. It is also necessary to inform Archicad that the add-on is prepared for merging module data: this can be done with the ACAPI_Register_ModulDataHandler function called from RegisterInterface.
In Teamwork mode it is also possible that the same module data is modified by the owner and by other team members. In this case the local and the server version of the data is conflicting at synchronization, and the add-on’s APIModulDataMergeHandlerProc is called to adjust the proper data.
When Archicad calls the handler function, the API_MDSetCmd moduldata event codes inform you about the type of the actual operation:
APIMDSetMerge_TW
The data sections should be merged because of a Teamwork operation (e.g. Receive changes).
APIMDSetMerge_HLM
The data section from a Hotlinked module should be merged into the main database.
APIMDSetMerge_Merge
The data section should be merged from a file which was merged into the main project, or from a paste or Drag&Drop operation.
Moduldata versions
The API_ModulData
structure contains a version number. If your data structure has to be changed, increase the version number. Upon retrieving the data section, check the version information and provide backward compatibility if possible.
Refer to the API_ModulData structure for more details.
Moduldata platforms
Since Archicad is a multi-platform application, all data written into the project file should be readable on the opposite platform too. As byte ordering is different on the Windows and on the Macintosh, for the correct interpretation the add-on needs to know on which platform the data was created. If the platform code differs from the actual platform, perform the necessary byte swapping operations using the GSRoot module, or use Memory Channel to read and write the custom data.
Refer to the API_ModulData structure for more details.
Saving data into old format project
If the structure of the custom data has changed since the previous version, you need to implement an APIModulDataSaveOldFormatHandlerProc callback function to be able to convert your modules when saving into an older format project. In order to be called this handler, the function pointer must be passed with ACAPI_Install_ModulDataMergeHandler, and the modul data handling feature must be registered with ACAPI_Register_ModulDataHandler.
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. The old format data should not be stored with ACAPI_ModulData_Store, nor the current data needs to be deleted or modified during the project save operation.
If the add-on does not install this converter callback routine, the available current format module data is saved into the old version project as well.
Other comments
Notice that it is not recommended to store unique ID-type references to Archicad elements in the module data; for this purpose try to use the Element Set Manager service instead.