User supplied callback procedure for converting modules into previous format.
typedef GSErrCode APIModulDataSaveOldFormatHandlerProc ( API_FTypeID planFileType, GS::HashTable<GS::UniString, API_ModulData*>& modulesToSave );
Parameters
- planFileType
- [in] The old format plan version the project is being saved. In Archicad 13 this can be only
APIFType_PlanFile1200
. - modulesToSave
- [out] A hash table to retrieve the converted module data.
Return Values
NoError
- The function has completed with success.
For other common API errors see the API Errors document.
Remarks
In order to save the add-on’s moduldata in the proper format into a previous version project file, you need to implement this callback function, and pass it to Archicad with ACAPI_Install_ModulDataSaveOldFormatHandler during the Initialize phase. It is also necessary to notify Archicad about this capability of the add-on by calling ACAPI_Register_ModulDataHandler from the RegisterInterface function.
This handler function is called whenever the user saves the project into an older format, and tha add-on has any moduldata stored currently into the project. The data should be constructed according to the required version into a dynamically allocated API_ModulData structure, and the pointer of this structure should be pushed into the modulesToSave table.
Notice that more modules can be added, should be identified with different names. In Archicad versions prior to 13 were able to store only one moduldata per add-on, this moduldata should be stored with empty string identifier (“”).
The memory allocated for the converted moduldata by the add-on’s handler function will be released by the caller application.
For further details of the notification process refer to the ModulData Manager section.
Example
Registration and installing callback:
GSErrCode __ACENV_CALL RegisterInterface (void) { ACAPI_Register_ModulDataHandler (); return NoError; } GSErrCode __ACENV_CALL Initialize (void) { GSErrCode err = ACAPI_Install_ModulDataSaveOldFormatHandler (APIModulDataSaveAsOldFormat); return err; }
Implementation of the handler function:
GSErrCode __ACENV_CALL APIModulDataSaveAsOldFormat (API_FTypeID planFileType, GS::HashTable<GS::UniString, API_ModulData*>& modulesToSave) { GSErrCode err = NoError; if (planFileType == APIFType_PlanFile1200) { GS::Array<GS::UniString> modulNameList; ACAPI_ModulData_GetList (&modulNameList); USize nObjects = modulNameList.GetSize (); if (nObjects > 0) { API_ModulData* oldFormatModulData = new API_ModulData; // must be allocated on the heap if (oldFormatModulData != nullptr) { BNZeroMemory (oldFormatModulData, sizeof (API_ModulData)); oldFormatModulData->dataVersion = 0; oldFormatModulData->platformSign = GS::Act_Platform_Sign; oldFormatModulData->dataHdl = BMAllocateHandle (nObjects * sizeof (Int32), 0, 0); if (oldFormatModulData->dataHdl != nullptr) { Int32* dataPtr = reinterpret_cast<Int32*> (*oldFormatModulData->dataHdl); for (GS::Array<GS::UniString>::ConstIterator it = modulNameList.Enumerate (); it != nullptr; ++it) { API_ModulData modulData; BNZeroMemory (&modulData, sizeof (API_ModulData)); if (ACAPI_ModulData_Get (&modulData, *it) == NoError) { *dataPtr = *(reinterpret_cast<Int32*> (*modulData.dataHdl)); dataPtr++; } BMKillHandle (&modulData.dataHdl); } modulesToSave.Put ("", oldFormatModulData); } else { err = APIERR_MEMFULL; } } } else { err = APIERR_NOMODULEDATA; } } return err; }
Refer to the ModulData Manager example add-on for more hints.
Requirements
- Version: API 13 or later
- Header: APIdefs_Callback.h
See Also
API_ModulData
ACAPI_Install_ModulDataSaveOldFormatHandler
ACAPI_Register_ModulDataHandler
ModulData Manager
API Functions