ACAPI_ModulData_Store |

Saves a custom data section into the project database.

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

Parameters

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

Return Values

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

For other common errors see the list of error codes.

Remarks

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.

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.

Example


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.

Requirements

Version: API 4.1 or later

Header: ACAPinc.h

Parameters

Return Values

Remarks

Example

Requirements

See Also