An Add-On is a DLL or shared library which is not loaded into the memory by default. ARCHICAD loads a normal Add-On into the memory only when the user invokes one of it’s commands. When the Add-On has finished its operation ARCHICAD unloads the Add-On again (unless certain conditions are met). This post describes further the way of how ARCHICAD manages Add-Ons.
In order to establish a connection between ARCHICAD and Add-Ons, each Add-On must export GetExportedFuncAddrs and SetImportedFuncAddrs functions. These functions are platform dependent, and are coded in the shipped libraries. When you create an Add-On the first thing you should do is just export them.
Add-On’s GetExportedFuncAddrs function defines the 4 required functions, which each Add-On must implement for ARCHICAD.
So the minimal source code you have to implement for an Add-On should looks like this:
#define ACExtension
#include "ACAPinc.h"
#include "RS.hpp"
API_AddonType __ACENV_CALL CheckEnvironment (API_EnvirParams *envirParams)
{
RSGetIndString (envirParams->addOnInfo.name, 32500, 1, ACAPI_GetOwnResModule ());
RSGetIndString (envirParams->addOnInfo.description, 32500, 2, ACAPI_GetOwnResModule ());
return APIAddon_Normal;
}
GSErrCode __ACENV_CALL RegisterInterface (void)
{
return NoError;
}
GSErrCode __ACENV_CALL Initialize (void)
{
return NoError;
}
GSErrCode __ACENV_CALL FreeData (void)
{
return NoError;
}It is very important to understand how the above listed 4 functions are called by the server application.
The following sequence diagram helps to understand the method how ARCHICAD enumerates through the available Add-Ons and loads them into the memory. By default ARCHICAD searches for Add-Ons recursively in the ‘Add-Ons’ folder next to the ARCHICAD application (note that the name of this folder is localised in the different language versions!).
ARCHICAD will try to load only the validated Add-Ons to the memory. If your Add-On cannot be validated then the Add-On Manager (you can reach the Add-On Manager from Options menu) says that “This add-on cannot be validated…”. It could have few reasons why ARCHICAD cannot validate an Add-On, we collected them in the FAQ.
This simplified diagram shows the lifecycle of the three most typical Add-On types.
CheckEnvironment
At first the CheckEnvironment function is called for each Add-Ons. In this function the Add-On can check the running environment (server application, main and sub-version, language version, etc.), and return whether it can run under the given conditions. For example, you can disable your Add-On in the demo version of ARCHICAD; or enable/disable certain commands.
Conditional Add-On returns APIAddon_DontRegister error code to show it’s not running under the actual environment. This informs the AddOnManager to skip the further steps for this Add-On.
Preloaded Add-On returns APIAddon_Preload to force ARCHICAD to preload (initialize) this Add-On before server application starts up. This Add-On wants to be kept in memory and install notification handlers in the Initialize function.
RegisterInterface
The RegisterInterface function is called after the enumeration and the dependency check. As such, only those Add-Ons are called which pass the first step. The Add-On should register its menu items and file types, add toolbox items, etc. here.
Initialize
The Initialize function is called right after the Add-On is loaded into the memory after the previous steps. This is the point where the Add-On should initialize itself, and install the callback functions which will be called by the server application when the user invokes the associated registered command.
Normal Add-On is reloaded to the memory when user invoked it’s command and this function called right after that. But in case of Preloaded Add-On, this function called only once before ARCHICAD started up (because Preloaded Add-On was kept in memory).
FreeData
The FreeData function is called right before the Add-On is going to be unloaded. This is the point where the Add-On should dispose the objects allocated in the Initialize function. The FreeData function is called in every case, no matter whether the Initialize or any of the callback functions has failed or not.
Preloaded Add-On was kept in the memory, so it’s FreeData function is called only once before ARCHICAD quits.
Note that you can instructs the server application to keep your Add-On in the memory using ACAPI_KeepInMemory function.
There are few API functions which force the Add-On to be kept in memory. For example notification manager functions (ACAPI_Notify_) require the Add-On to be in the memory in oder to call it’s registered event handler function when the observed event has occurred.
Please refer to the document Control the Load/Unload Mechanism to get further details on these functions.