Archicad 28 C++ API
Loading...
Searching...
No Matches
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;
}
GSErrCode FreeData(void)
void ACAPI_SetDllTermHookProc(APIDllTermHookProc *dllTermHookProc)
Sets a handler procedure for the case of abnormal termination.
GSErrCode Initialize(void)
The main entry point of the add-on.

Enumeration Type Documentation

◆ 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

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
{
//
// Fill in the necessary information
//
RSGetIndString (&envir->addOnInfo.name, 32000, 1, ACAPI_GetOwnResModule ());
RSGetIndString (&envir->addOnInfo.description, 32000, 2, ACAPI_GetOwnResModule ());
//
// Register command services
//
if (err != NoError)
return APIAddon_DontRegister;
return APIAddon_Normal;
} // CheckEnvironment
GSErrCode ACAPI_AddOnAddOnCommunication_RegisterSupportedService(GSType cmdID, Int32 cmdVersion)
Registers a command which can be used by other add-ons.
API_AddonType
Describes the different types of add-ons.
Definition: APIdefs_Registration.h:253
API_AddonType CheckEnvironment(API_EnvirParams *envirParams)
Defines the behavior of the add-on based on the current running environment.
GSResModule ACAPI_GetOwnResModule(void)
Returns the add-on's own resource module identifier for loading resources.
GS::UniString description
The description of the functionality of the add-on, in Unicode.
Definition: APIdefs_Registration.h:117
GS::UniString name
The name of the add-on, in Unicode.
Definition: APIdefs_Registration.h:111
Describes the different parameters of the running environment.
Definition: APIdefs_Registration.h:195
API_AddOnInfo addOnInfo
Textual description of the add-on; the add-on should fill this in.
Definition: APIdefs_Registration.h:207

◆ 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;
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
GSErrCode ACAPI_GetOwnLocation(IO::Location *ownFileLoc)
Returns the location of the add-on in the file system.
GSErrCode ACAPI_Element_CatchChangeDefaults(const API_ToolBoxItem *elemType, APIDefaultsChangeHandlerProc *handlerProc)
Register or unregister your add-on to be notified if the default settings of a given element type is ...
GSErrCode ACAPI_MenuItem_InstallMenuHandler(short menuStrResID, APIMenuCommandProc *handlerProc)
Installs a callback procedure for handling the add-on's menu commands.
GSErrCode ACAPI_ProjectOperation_CatchProjectEvent(GSFlags eventTypes, APIProjectEventHandlerProc *handlerProc)
Register or unregister your add-on to be notified of application and project events.
Data of the active toolbox mode.
Definition: APIdefs_Environment.h:721
API_ElemType type
Toolbox item element type.
Definition: APIdefs_Environment.h:727

◆ 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
GSErrCode ACAPI_AddOnIntegration_RegisterFileType(Int32 refCon, GSType ftype, GSType fcreator, const char *extname, short iconResID, short descStrResID, short descStrResItemID, API_IOMethod methodFlags)
Registers a file type for I/O type add-ons.
GSErrCode RegisterInterface(void)
In this function the add-on can register its services, and menu commands.
GSErrCode ACAPI_MenuItem_RegisterMenu(short menuStrResID, short promptStrResID, APIMenuCodeID menuPosCode, GSFlags menuFlags)
Registers the menu items of the add-on.