Add-On Lifetime

Functions defining the Add-On's behavior during its lifetime, including the initial registration by Archicad, loading into memory and unloading. More...

Classes
struct	API_AddOnInfo
	Textual description of the add-on. More...
struct	API_ServerApplicationInfo
	Describes the current server application the add-on is running under. More...
struct	API_EnvirParams
	Describes the different parameters of the running environment. More...

Typedefs
typedef void	APIDllTermHookProc(void)
	Handler procedure for abnormal termination.

Enumerations
enum	API_ApplicationTypeID { APIAppl_ArchiCADID = 1 }
	The ID of the server application the add-on is called from. More...
enum	API_AddonType { APIAddon_DontRegister = 0 , APIAddon_Normal = 1 , APIAddon_Preload = 2 , APIAddon_Unknown = 9999 }
	Describes the different types of add-ons. More...

Functions
API_AddonType	CheckEnvironment (API_EnvirParams *envirParams)
	Defines the behavior of the add-on based on the current running environment.
GSErrCode	RegisterInterface (void)
	In this function the add-on can register its services, and menu commands.
GSErrCode	Initialize (void)
	The main entry point of the add-on.
GSErrCode	FreeData (void)
void	ACAPI_SetDllTermHookProc (APIDllTermHookProc *dllTermHookProc)
	Sets a handler procedure for the case of abnormal termination.
void	ACAPI_KeepInMemory (bool keepIn)
	Instructs the host application to keep the add-on in the memory after execution.

Detailed Description

Functions defining the Add-On's behavior during its lifetime, including the initial registration by Archicad, loading into memory and unloading.

Typedef Documentation

APIDllTermHookProc

typedef void APIDllTermHookProc(void)

Handler procedure for abnormal termination.

Remarks

Set this hook procedure with the ACAPI_SetDllTermHookProc function in order to be called when the application does not terminate in the normal way. Generally this function should do the same as FreeData does.

Example

#include "IOUtilities.hpp"
 
static IOUtil::ModuleFile* additionalModule = nullptr;
 
//------------------------------------------------------
// Called in case of abnormal termination
//------------------------------------------------------
static void MyDllTermHookProc (void)
{
    if (additionalModule != nullptr) {
        additionalModule->UnLoad ();
        delete additionalModule;
        additionalModule = nullptr;
    }
    return;
}
 
//------------------------------------------------------
// Called when the Add-On has been loaded into memory
// to perform an operation
//------------------------------------------------------
GSErrCode Initialize (void)
{
    additionalModule = new IOUtil::ModuleFile (IO::Location("AdditionalLibrary.DLL"));
    if (additionalModule != nullptr) {
        if (additionalModule->Load () != NoError || additionalModule->GetProcAddress ("ExportedAdditionalFunction") == nullptr) {
            additionalModule->UnLoad ();
            delete additionalModule;
            additionalModule = nullptr;
        }
    }
 
    ACAPI_SetDllTermHookProc (MyDllTermHookProc);
    return NoError;
}
 
//------------------------------------------------------
// Called when the Add-On is going to be unloaded
//------------------------------------------------------
GSErrCode FreeData (void)
{
    if (additionalModule != nullptr) {
        additionalModule->UnLoad ();
        delete additionalModule;
        additionalModule = nullptr;
    }
    return NoError;
}

Enumeration Type Documentation

API_AddonType

enum API_AddonType

Describes the different types of add-ons.

Remarks

This is the return value of the CheckEnvironment function and specifies the behavior of the current add-on in the running environment.

API_ApplicationTypeID

enum API_ApplicationTypeID

The ID of the server application the add-on is called from.

Remarks

Use these data if you have to depend on the server application. Call the ACAPI_AddOnIdentification_Application or the ACAPI_GetReleaseNumber functions to get this data.

Function Documentation

ACAPI_KeepInMemory()

void ACAPI_KeepInMemory

(

bool

keepIn

)

Instructs the host application to keep the add-on in the memory after execution.

Parameters

keepIn

[in] If true the add-on will stay in the memory.

Remarks

This function is used to keep the add-on in the memory. You should call this function with true each time your add-on is called to stay in memory. The values of all your global variables stay the same between the calls to your add-on. Also, when in memory, the Initialize and the FreeData functions of your add-on are not called. See more about this topic at the Control the Load/Unload Mechanism part of the Tips and Tricks.

ACAPI_SetDllTermHookProc()

void ACAPI_SetDllTermHookProc

(

APIDllTermHookProc *

dllTermHookProc

)

Sets a handler procedure for the case of abnormal termination.

Parameters

dllTermHookProc

[in] Handler function pointer

Remarks

Normally the FreeData function of the add-on is called before the add-on module is unloaded from the memory. However in some exceptional cases the application terminates without properly unloading the add-ons. For handling these situations you can set a hook procedure with the ACAPI_SetDllTermHookProc function. This might be useful if, for example, you have loaded additional modules (DLLs) from your add-on, and you want to unload them even in the case of abnormal termination.

Example

#include "IOUtilities.hpp"
 
static IOUtil::ModuleFile* additionalModule = nullptr;
 
//------------------------------------------------------
// Called in case of abnormal termination
//------------------------------------------------------
static void MyDllTermHookProc (void)
{
    if (additionalModule != nullptr) {
        additionalModule->UnLoad ();
        delete additionalModule;
        additionalModule = nullptr;
    }
    return;
}
 
//------------------------------------------------------
// Called when the Add-On has been loaded into memory
// to perform an operation
//------------------------------------------------------
GSErrCode Initialize (void)
{
    additionalModule = new IOUtil::ModuleFile (IO::Location("AdditionalLibrary.DLL"));
    if (additionalModule != nullptr) {
        if (additionalModule->Load () != NoError || additionalModule->GetProcAddress ("ExportedAdditionalFunction") == nullptr) {
            additionalModule->UnLoad ();
            delete additionalModule;
            additionalModule = nullptr;
        }
    }
 
    ACAPI_SetDllTermHookProc (MyDllTermHookProc);
    return NoError;
}
 
//------------------------------------------------------
// Called when the Add-On is going to be unloaded
//------------------------------------------------------
GSErrCode FreeData (void)
{
    if (additionalModule != nullptr) {
        additionalModule->UnLoad ();
        delete additionalModule;
        additionalModule = nullptr;
    }
    return NoError;
}

CheckEnvironment()

API_AddonType CheckEnvironment

(

API_EnvirParams *

envirParams

)

Defines the behavior of the add-on based on the current running environment.

Parameters

envirParams

[in/out] Contains information on the environment. The add-on should also return a textual description of its purpose.

Returns

• type of add-on.

Remarks

This is one of the main entry points of add-ons; each add-on should implement this function. It is called when the Add-On Manager is enumerating the add-ons during application startup. After collecting the all the information from the different add-ons, the Add-On Manager performs a dependency check, then calls the RegisterInterface function of the "good" add-ons. The add-on can check the running environment (server application, main and sub-version), 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. This function is also the place to inform other add-ons about the availability of certain services of your add-on (see ACAPI_AddOnAddOnCommunication_RegisterSupportedService), and also to tell the server application that your add-on requires services of other add-ons (see ACAPI_AddOnIntegration_RegisterRequiredService).

Example

API_AddonType CheckEnvironment (API_EnvirParams* envir)
{
    //
    // Fill in the necessary information
    //
    RSGetIndString (&envir->addOnInfo.name, 32000, 1, ACAPI_GetOwnResModule ());
    RSGetIndString (&envir->addOnInfo.description, 32000, 2, ACAPI_GetOwnResModule ());
 
    //
    // Register command services
    //
    GSErrCode err = ACAPI_AddOnAddOnCommunication_RegisterSupportedService ('ABCD', 4L);
    if (err != NoError)
        return APIAddon_DontRegister;
 
    return APIAddon_Normal;
}   // CheckEnvironment

FreeData()

GSErrCode FreeData

(

void

)

The termination point of the addon.

Returns

• NoError - The function has completed with success.

Remarks

You can use this function as the termination point of your code. It is called right before the DLL/code fragment is to be unloaded from the memory. This is the place where you can free your dynamic memory blocks, and unload the loaded modules. This function will be called in conjunction with the Initialize function. You can be sure that the FreeData function will be called only if this function was called before, even if any error code returned in the Initialize or the different callback functions. If your add-on has user interface, and you want to use a context sensitive help engine (you want to use not just tooltips, but help anchors too), and you registered your own help engine's path with your add-on's MDID in the Initialize function, then you should uninitialize this data here. In some exceptional cases the application terminates without calling the FreeData function of the add-ons. In these situations the system unloads the add-on modules. If you need to be called to handle these abnormal termination cases, set an APIDllTermHookProc with the ACAPI_SetDllTermHookProc function.

Example

GSErrCode FreeData (void)
{
    BMhFree ((GSHandle) handle);
 
    // If you used RegisterAdditionalHelpLocation in Initialize function
    DG::UnregisterAdditionalHelpLocation (MDID_APICD, MDID_APICD_InterfaceFunctions);
 
    return NoError;
}

Initialize()

GSErrCode Initialize

(

void

)

The main entry point of the add-on.

Returns

• NoError - The initialization procedure has completed with success.

Remarks

You can use this function as the main entry point of your code. It is called by the library right after the DLL/code fragment has been loaded into the memory, and the communication channels are set up correctly. This is the place where you can initialize your global variables, dynamic memory blocks etc. In this function you will also have to install the callback functions for the different services you registered in the CheckEnvironment and RegisterInterface routines. Also you can install the notification handlers here. If your add-on has user interface, and you want to use a context sensitive help engine (you want to use not just tooltips, but help anchors too), then this is the place where you can register your own help engine's path with your add-on's MDID (see DG::RegisterAdditionalHelpLocation in the example code).

Example

typedef struct {
   double   len;
   Int32     index;
} NType;
 
GSHandle  **handle;
Int32     nAlloc;
Int32     nElem;
 
 
// -----------------------------------------------------------------------------
// Called after the Add-On has been loaded into memory
// -----------------------------------------------------------------------------
GSErrCode Initialize (void)
{
    // If the add-on has user interface and wants to use context sensitive help engine
    IO::Location helpLoc;
    ACAPI_GetOwnLocation (&helpLoc);
    DG::RegisterAdditionalHelpLocation (MDID_DeveloperID, MDID_LocalID, helpLoc);
 
    //
    // Allocate globals
    //
    nAlloc = 8;
    nElem  = 0;
    handle = (NType **) BMhAll (nAlloc * sizeof (NType));
    if (handle == nullptr)
        return APIERR_MEMFULL;
 
    //
    // Install the menu handler procedure
    //
    GSErrCode err = ACAPI_MenuItem_InstallMenuHandler (32500, MenuCommandHandler);
    if (err != NoError)
        DBPrintf ("Initialize():: ACAPI_MenuItem_InstallMenuHandler failed\n");
 
    //
    // Install the change defaults notification handler procedure
    //
    API_ToolBoxItem toolBoxItem;
    BNZeroMemory (&toolBoxItem, sizeof (API_ToolBoxItem));
    toolBoxItem.type = API_ZombieElemID;                // for all types
    err = ACAPI_Element_CatchChangeDefaults (&toolBoxItem, APIDefaultsChangeHandler);
    if (err == NoError) {
        err = ACAPI_ProjectOperation_CatchProjectEvent (APINotify_Close, APIProjectEventHandler);
    }
 
    return err;
}   // Initialize

RegisterInterface()

GSErrCode RegisterInterface

(

void

)

In this function the add-on can register its services, and menu commands.

Returns

• NoError - The function has completed with success.

Remarks

This function registers the different services of your add-on: menu commands, file types, commands other add-on can call, toolbox items, or library part subtypes. Here you can obtain information on the server application, on the protection, and the availability of the services of other add-ons as well; and adjust the registration depending on this information. The actual callback functions which handle the events and notifications coming from the server application are installed in the Initialize function of your add-on. The actual callback functions which handle the events and notifications coming from the server application are installed in the Initialize function of your add-on.

Example

GSErrCode RegisterInterface (void)
{
    //
    // Register menu
    //
    GSErrCode err = ACAPI_MenuItem_RegisterMenu (32500, 32501, MenuCode_Options1, MenuFlag_Default);
    if (err != NoError)
        return err;
 
    //
    // Register an IO
    //
    err = ACAPI_AddOnIntegration_RegisterFileType (1, 'GSAC', ' DWF', "dwf", 0, 32500, 1,
                                   SaveAs2DSupported + Open2DSupported + Merge2DSupported);
    return err;
}   // RegisterInterface