APIModulDataMergeHandlerProc

User supplied callback procedure for handling module data merge operations.

    typedef GSErrCode  APIModulDataMergeHandlerProc (
        API_MDSetCmd             mode,
        const GS::UniString&     modulName,
        const API_ModulData*     originalInfo,
        const API_ModulData*     toMergeInfo,
        API_ModulData*           destInfo
    );

 

Parameters

mode
[in] The operation the add-on is called for.
modulName API 13 feature
[in] Identifier name of the modul data (for modules stored in previous versions this parameter is always empty string).
originalInfo
[in] The original module data in the to which data has to be merged into.
toMergeInfo
[in] The incoming module data.
destInfo
[out] The result module data. Your add-on should put the result of the merge in here.

 

Return Values

NoError
The function has completed with success.

For other common API errors see the API Errors document.

 

Remarks

This is the function to be called when two conflicting modules need to be merged by your add-on. The handler function pointer must be passed with ACAPI_Install_ModulDataMergeHandler.

API 13 feature  It is also necessary to register this functionality of the add-on with calling ACAPI_Register_ModulDataHandler.

The details of the notification process are described in 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_ModulDataMergeHandler (APIModulDataMergeHandler);
    return err;
}

Implementation of the handler function:


GSErrCode __ACENV_CALL  APIModulDataMergeHandler (API_MDSetCmd          mode,
                                                  const GS::UniString&  /*modulName*/,
                                                  const API_ModulData*  originalInfo,
                                                  const API_ModulData*  toMergeInfo,
                                                  API_ModulData*        destInfo)
{
    if (toMergeInfo == nullptr || destInfo == nullptr)
        return APIERR_BADPARS;

    const API_ModulData* modulDataToKeep = (mode == APIMDSetMerge_TW || originalInfo == nullptr) ? toMergeInfo : originalInfo;

    if (modulDataToKeep->dataHdl != nullptr) {
        BNZeroMemory (destInfo, sizeof (API_ModulData));
        destInfo->dataVersion = modulDataToKeep->dataVersion;
        destInfo->platformSign = modulDataToKeep->platformSign;
        BMHandleToHandle (modulDataToKeep->dataHdl, &destInfo->dataHdl);
    } else
        return APIERR_BADPARS;

    return NoError;
}

Refer to the ModulData Manager example add-on for more hints.

 

Requirements

Version: API 4.1 or later
Header: APIdefs_Callback.h

 

See Also

API_MDSetCmd
API_ModulData
ACAPI_Install_ModulDataMergeHandler
ACAPI_Register_ModulDataHandler
ModulData Manager
API Functions