Required Functions

When you develop your own add-on, you have to link the appropriate API library to your object files. This library basically contains two function sets.

It owns the main initialization and termination points of your DLL/shared library.
Sets up the communication channels between Archicad and the add-on.
API functions listed in the ACAPinc.h header file. You call these to work on the Archicad database.

There are four functions which must be coded in order to be able to link your add-on to the library.

The prototypes of these functions are also listed in the ACAPinc.h header file.

Most of these functions (except CheckEnvironment) return an error code based on the type definition GSErrCode. The value NoError means that no error occurred, any non-zero value indicates some kind of error.

It is very important to understand how the above listed 4 functions are called by the server application.

An add-on is a DLL or shared library which is not loaded into the memory by default. When the user invokes one of the commands of an add-on Archicad loads it into the memory to execute the command. When the add-on has finished its operation Archicad unloads the add-on again (unless certain conditions are met).

The CheckEnvironment function

The CheckEnvironment function is called when the Add-On Manager enumerates the add-ons. The add-on can check the running environment and define its own behavior, for example it can disable itself in the demo version. The add-on is loaded and unloaded during this step, but the Initialize and FreeData functions are not called.

Notes: the following two points may have a serious effect on the startup time of the server application.

all your global and (non-function) static variables are initialized during this step.
return the appropriate error code (APIAddon_DontRegister) if you are not running under the desired server application. This informs the AddOnManager to skip the further steps for your add-on.

The RegisterInterface function

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, or add toolbox items here. The add-on is loaded and unloaded during this step, but the Initialize and FreeData functions are not called.

Note: all your global and (non-function) static variables are initialized during this step.

The Initialize function

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.

The FreeData function

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.

Keep your global variables in known state, if it is done you will have no problem to dispose them. Basic initialization and allocation should be done in the Initialize function, and you can done the inverse in the FreeData function.

Please refer to the document Control the Load/Unload Mechanism to get further details on these functions.

Skeleton of an add-on

The minimal source code you have to implement should looks like this:

#define ACExtension
#include "ACAPinc.h"
 
API_AddonType CheckEnvironment (API_EnvirParams *envirParams)
{
    RSGetIndString (&envirParams->addOnInfo.name, 32500, 1, ACAPI_GetOwnResModule ());
    RSGetIndString (&envirParams->addOnInfo.description, 32500, 2, ACAPI_GetOwnResModule ());
 
    return APIAddon_Normal;
}
 
GSErrCode RegisterInterface (void)
{
    return NoError;
}
 
GSErrCode Initialize (void)
{
    return NoError;
}
 
GSErrCode FreeData (void)
{
    return NoError;
}

This skeleton can be compiled, linked and also executed, however it does nothing.