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 , APIAppl_MEPDesignerID = 2 }
	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 add-on's behavior 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 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.

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.

Enumerator
APIAddon_DontRegister	Some parameters, such as the server application version, are incorrect; the add-on will not be loaded.
APIAddon_Normal	The add-on can operate in the current environment. This is the default return value.
APIAddon_Preload	The add-on requires loading when the server application starts up, such as when it needs to perform a lengthy initialization.
APIAddon_Unknown	The add-on type is unknown.

◆ 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.

Enumerator
APIAppl_ArchiCADID	Indicates that the server application is Archicad.
APIAppl_MEPDesignerID	Indicates that the server application is MEP Designer.

Function Documentation

◆ ACAPI_KeepInMemory()

void ACAPI_KeepInMemory ( bool keepIn )

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

Parameters

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

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, your add-on's Initialize and FreeData functions are not called. See more about this topic in the Tips and Tricks' Control the Load/Unload Mechanism section.

◆ 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 memory. However, in some exceptional cases, the application terminates without properly unloading the add-ons. To handle 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 want to unload them even in the case of abnormal termination.

◆ CheckEnvironment()

API_AddonType CheckEnvironment ( API_EnvirParams * envirParams )

Defines the add-on's behavior 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 enumerates the add-ons during application startup. After collecting 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 turn off your add-on in the demo version of Archicad or turn specific commands on/off. 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;

}

◆ FreeData()

GSErrCode FreeData ( void )

The termination point of the add-on.

Returns

NoError - The function has completed successfully.

Remarks: You can use this function as the termination point of your code. It is called right before the DLL/code fragment is unloaded from memory. This is 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 was returned in the Initialize or the different callback functions. If your add-on has a 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 ()

{

// 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 successfully.

Remarks: You can use this function as the main entry point of your code. The library calls it right after the DLL/code fragment has been loaded into memory and the communication channels are set up correctly. This is where you can initialize your global variables, dynamic memory blocks, etc. In this function, you must install the callback functions for the different services you registered in the CheckEnvironment and RegisterInterface routines. You can also install the notification handlers here. If your add-on has a 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 ()

{

// 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, &GS::EmptyUniString, &GS::EmptyUniString, nullptr, &GS::EmptyUniString);

//

// 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 {};

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 successfully.

Remarks: This function registers your add-on's different services: menu commands, file types, commands other add-ons can call, toolbox items, or library part subtypes. Here, you can obtain information on the server application, the protection, and the availability of other add-ons' services, and adjust the registration based on this information. Your add-on's Initialize function installs the callback functions that handle the events and notifications from the server application.

Example: GSErrCode RegisterInterface ()

{

//

// 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

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ APIDllTermHookProc

Enumeration Type Documentation

◆ API_AddonType

◆ API_ApplicationTypeID

Function Documentation

◆ ACAPI_KeepInMemory()

◆ ACAPI_SetDllTermHookProc()

◆ CheckEnvironment()

◆ FreeData()

◆ Initialize()

◆ RegisterInterface()