Saves a custom data section into the project database.

    GSErrCode  ACAPI_ModulData_Store (
        const API_ModulData*     info,
        const GS::UniString&     modulName = ""



[in] The module data to store. It also includes platform and version information.
modulName API 13 feature
[in] Identifier name of the modul data (optional).


Return Values

the function completed successfully
the passed dataHdl parameter is nullptr
the platformSign passed in info is not valid
no custom data section is saved into the project file to be deleted
failed memory allocation
a general error

For other common errors see the list of error codes.



This function is used to embed a custom data section into the project database.

The data section in the project is identified uniquely using the ‘MDID’ of the caller add-on and the passed modulName identifier.

The dataHdl handle has to be allocated and released using the BM memory manager functions of the GSRoot module. The data content can be copied into the handle directly, or you can use the allocated memory block as a memory channel (see IO::MemoryOChannel).

In order to remove the saved module data from the project, you can simply pass nullptr pointer in the info parameter. The same effect can be achieved with the ACAPI_ModulData_Delete function.

To retrieve the stored section use the ACAPI_ModulData_GetInfo and ACAPI_ModulData_Get functions.

API 13 feature  You can also get a list of names of all modules stored by the add-on with the ACAPI_ModulData_GetList function.

If you need to save different format moduldata back into previous version project file, you should implement an APIModulDataSaveOldFormatHandlerProc callback function, which prepares the necessary data in the format corresponding to the project version.

You might also need to merge data of the modules conflicting due to a merge or Teamwork receive operation. In order to properly resolve the conflicts you can implement an APIModulDataMergeHandlerProc callback function. For further details refer to the ModulData Manager overview.

This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.



GSErrCode MyDataClass::SaveIntoModulData (void)
    GSErrCode err = NoError;

    API_ModulData info;
    BNZeroMemory (&info, sizeof (API_ModulData));
    info.dataVersion = 1;
    info.platformSign = GS::Act_Platform_Sign;
    info.dataHdl = BMAllocateHandle (sizeof (myDataClassIntMember), 0, 0);
    if (info.dataHdl != nullptr) {
        *(reinterpret_cast<Int32*> (*info.dataHdl)) = myDataClassIntMember;
        err = ACAPI_ModulData_Store (&info, "MyFirstDataBlock");
        BMKillHandle (&info.dataHdl);
    } else {
        err = APIERR_MEMFULL;

    return err;

For more hints you can also study the ModulData Manager example add-on.



Version: API 4.1 or later
Header: ACAPinc.h


See Also

ModulData Manager
API Functions