Building a plug-in requires the creation of a function handle(class AlFunctionHandle). The function handle encapsulates all the operations on a UI menu button. A plug-in can define and control any number of menu buttons. A plug-in must define a entry function called plugin_init(). The exit function called plugin_exit() is optional. Plug-ins without exit functions will not be unloaded.
This function must be defined as:
extern “C” PLUGINAPI_DECL int plugin_init( const char* pluginDirPath )
It is run as soon as the plug-in is loaded. pluginDirPath is a NULL-terminated string which contains the absolute pathname to the directory that the plug-in was loaded from. This path is provided as a convenience to the plug-in. It is intended to be passed to the initialization routines as an additional argument. This allows the plug-in to specify the exact location of its scheme and icon files if they are not located in the default directories.
On Windows, PLUGINAPI_DECL is defined to export the associated symbol from the plug-in. On Mac, PLUGINAPI_DECL is not needed—it is an empty define.
The developer uses this function to initialize the OpenAlias universe, and uses instances of the AlFunctionHandle class and AlMomentaryFunction or AlContinuousFunction classes (declared in the file scope to be available to the plugin_exit() function as well) to define the interface between Alias and the plug-in. On successful completion this function should return zero. If a non-zero value is returned from the plugin_init function, OpenAlias will assume that some error condition was encountered in initialization and will unload the plug-in.
This function must be declared as:
extern “C” PLUGINAPI_DECL int plugin_exit( void )
It is called when the plug-in is removed or Alias is shut down. The programmer uses this function to do whatever is necessary to clean up the plug-in. This function should remove the plug-in from all menus using the deleteObject() method for each declared AlFunctionHandle and destroy any created AlFunctions using the deleteObject() method. On successful completion this function should return zero. Failing to remove all references may result in core dumps if they are accessed by Alias after the plug-in has been removed. In addition, ensure that any callbacks that have been installed are removed.
Static destructors and exiting from Alias
Plug-ins are not unloaded when Alias exits. This decreases the time that Alias takes to exit but results in static destructors of C++ classes not being called. The DSO is not explicitly unloaded but is removed when Alias exits.
Static destructors are called when a plug-in is unloaded manually. We suggest not doing operations within the static destructors of your classes. Note that plugin_exit() is still called when Alias exits, so any saving of data can be done within that function.
