A plugin component is used as part of a larger computation process. At the start of the process, the plugin component will be created using standard COM technology. The Windows registry will be searched for the ProdId to determine the GUID for the component which will then be used to find the dynamic link library (dll) that defines the component. The dll will then be loaded into memory and initialized. After this step, the plugin component will be created. The application now can call the plugin component's functions according to the interface defined by the plugin point.
Often, the plugin point interface will have a function call (usually called Init()) to inform the plugin component that the computational process has started. During this call, the plugin can perform operations that should be done only once during a computational process (e.g. opening up a database connection, opening a files for logging data, etc.). By returning a value of true, the plugin component informs the application that it is ready and able for further use during the computation. If it returns false, then the plugin is not considered enabled. A success or failure message will be written to the message viewer. Similarly, at the end of the computational process, the plugin point interface will have a function call (usually called Free()) to inform the plugin component that the computational process has ended. This allows the plugin to perform any cleanup operations (e.g., close a database connection, close a file, etc.).
A plugin component is called at certain well-defined events, defined by plugin point interface, within a computational cycle. Each plugin point defines its own event times.
As an example, the HPOP Force Model plugin point, defined by IAgAsHpopPlugin, provides the following function calls made at the event times listed:
The whole point of the plugin is to modify the current computation in some manner. To do that, the plugin must be able to obtain all the relevant data so that it can then make modifications and enhancements as necessary. The plugin obtains inputs and sets outputs through an interface that is provided to the plugin by the application on its event calls. Each event function call involves passing one argument (except for Free() which has no arguments). That argument is itself a COM object that allows the plugin function to access data inside the application.
For example, the sole argument of the Evaluate() method of IAgAsHpopPlugin is IAgAsHpopPluginResultEval. The IAgAsHpopPluginResultEval interface provides methods and properties for obtaining data used in evaluating the force model.
The outputs permitted by the interface define the purpose of the function call (e.g., the Evaluate() call of a force model plugin provides a means to model time-varying parameters and to add other acceleration sources). Because each plugin has a very specific task, its possible outputs are limited by design (but even then there are still quite a few). The inputs to a plugin are another matter entirely: the plugin would be of little use if the inputs that were needed to create the outputs were unavailable from the application. This concern has been addressed by providing an interface argument with a very large number of possible inputs. In addition, plugin components with an Init() method are passed a IAgUtPluginSite interface which may provide additional sources of input data to the plugin (see The Site Interface).
A plugin function call must return true to indicate to the application that the function call was successful. If the function call experiences an error condition, it can let the application know by returning the value false. When this occurs, an output message is made in the message window and the function call is no longer called by the application (although other function calls supported by the plugin will still be called as appropriate).
STK Programming Interface 11.0.1