ACAPI_​ModulData_​Get

Returns the data section stored in the project database.

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

 

Parameters

info
[out] Contains the the custom data stored in the project file on return.
modulName API 13 feature
[in] Identifier name of the modul data (optional).

 

Return Values

NoError
The function has completed successfully.
APIERR_BADPARS
The info parameter is nullptr.
APIERR_NOMODULEDATA
No custom data section is saved into the project file identified by the add-on’s unique modul ID and the modulName parameter.

For other common errors see the list of error codes.

 

Remarks

This function is used to retrieve the data bytes of the custom data section embedded into the project database, identified with the given modulName.

  • Always check the platformSign returned in the API_ModulData structure. Call the necessary byte swapping methods to ensure correct data format. Refer to the GSRoot documentation to have further details on the byte swapping methods.
  • Always check the dataVersion returned in the API_ModulData structure. Old data formats should be handled to keep backward compatibility (see also APIModulDataSaveOldFormatHandlerProc).

ARCHICAD allocates the target buffer in the dataHdl field of info; the caller add-on is responsible to dispose it with BMKillHandle.

In order to check whether there is moduldata with the specified identifier stored into the current project, it is recommended to use the ACAPI_ModulData_GetInfo function, which does not retrieves the data itself but the version and platform information.

 

Example


GSErrCode MyDataClass::LoadFromModulData (void)
{
    API_ModulData  info;
    GSErrCode      err;

    BNZeroMemory (&info, sizeof (API_ModulData));
    err = ACAPI_ModulData_GetInfo (&info, "MyFirstDataBlock");
    if (err != NoError) {
        if (err == APIERR_NOMODULEDATA)
            err = NoError;
        return err;
    }

    err = ACAPI_ModulData_Get (&info, "MyFirstDataBlock");
    if (err == NoError && info.dataVersion == 1) {
        myDataClassIntMember = *(reinterpret_cast<Int32*> (*info.dataHdl));
        if (info.platformSign != GS::Act_Platform_Sign) {   // swap data bytes
            IVLong ((GS::PlatformSign) info.platformSign, &myDataClassIntMember);
        }
    }

    BMKillHandle (&info.dataHdl);
    return err;
}

 

Requirements

Version: API 4.1 or later
Header: ACAPinc.h

 

See Also

API_ModulData
ACAPI_ModulData_GetInfo
ACAPI_ModulData_GetList
ACAPI_ModulData_Store
ModulData Manager
API Functions