Plugin Components

A plugin component is a software component built using Microsoft's COM technology. There are two types: (i) compiled code (usually a dynamic link library) and (ii) script code.

Compiled code may be implemented in a variety of languages (C++, C#, Visual Basic .NET, etc.) that support COM interfaces. Compiled code will be executed almost as fast as the application program itself. Another advantage is that you can debug your component using a standard debugger while it is in use. Of course, any modification of the code requires recompilation before it can be used. While a C++ COM component can be used, modified, rebuilt, and used again while the application is still running, COM components built using a .NET language (C#, VB.NET, etc.) cannot---they can only be rebuilt once the application has exited.

Script code is implemented using Windows Script Components (WSC). They can be implemented in a variety of languages (VBScript, JScript, PerlScript, Python, etc.). Although the script code is slower to execute than compiled code, scripts can be edited after each run. They cannot be debugged, however. Often, proof-of-concepts are developed using scripts before being written in a compiled language for speed.

Many users may wish to use Matlab to perform their computations. Matlab is COM-aware and can be called through a COM interface. To use Matlab in a plugin, it is recommended that you create a Windows script component using a script language, and communicate with Matlab through its COM object model. Samples are provided that use a VBScript component that opens up Matlab and calls a Matlab m-file to perform a computation. Because Matlab is an application, not just a dynamic link library (DLL), function calls made between the plugin and Matlab are likely to be very much slower than just using the scripting environment itself (which of course is slower than using a compiled language).Speed penalties of up to 50x over the use of the scripting environment itself have been observed.

Building Plugin Components

Plugin components are built using Microsoft's COM technology, developed in the mid 1990's. It is the precursor technology to Microsoft's .NET framework. There are many books, courses, and online help concerning COM technology. All the sample code provided was built using Microsoft's Visual Studio .NET 2003.

It is best to use one of the samples provided as a guide. You can even modify the provided code to see how a feature will work. If you are unfamiliar with programming languages in general, then we would recommend C# for the compiled code and JScript for the script code, unless you know Perl. While VB.Net and VBScript were developed to make programming simple, C and C++ based programmers may feel ill at ease with these languages.

NOTE: A program uninstall/reinstall will delete the example plugins and any changes made to them will be lost. It is recommended that you copy the examples to your own directories if you wish to modify them.

Essentially, each plugin point defines a functional interface that the plugin component must implement. The plugin help will identify the required methods. A method must be provided even if the plugin does not use it --- it can turn a method off however to prevent it from being called unnecessarily and wasting time.

NOTE: Because each plugin component is a COM object, it must follow certain COM paradigms. Most importantly, each different plugin must have a unique GUID (Globally Unique Identifier). Visual Studio provides the GuidGen.exe program that generates unique GUIDs. For users without Visual Studio, download the Windows Script Component Wizard from which can also generate GUIDs. It is very important not to have more than one component registered in the Windows registry with the same GUID.

Sample Plugins

Sample plugins have been provided for each of the plugin points. See <INSTALL_DIR>\CodeSamples\Extend\ODTK\. Each sample has been programmed in a several programming languages. A scenario demonstrating the use of the sample code has also been provided. Note that you will need to build the compiled examples to see their use; you will need to register the windows script components to see their use (See Installation and Deployment below). Moreover, for Perl and Python examples, you will need to install perl/python from (available as a download from their web site for free).

NOTE: In addition to registration in the windows registry, plugins must also be registered with a plugin point in ODTK . This registration is done using xml registration files. Registration files are provided for all of the sample plugins in the sample code area. After registering a sample plugin, the corresponding registration file needs to be copied to an appropriate folder. See Registration as a Plugin Point below.

Registration in the Windows Registry

Because each plugin component is a COM object, it must be registered for use in the Windows registry. You must have administrative rights to add components to the Windows registry. In the sample code provided for the compiled languages, the build settings have been configured to automatically register the sample plugin component during the build. Windows script components are not compiled but still must be registered. The registration associates a GUID and ProgID defined by the component.

Regsvr32.exe requires administrator rights in order to register a plugin. Once registered, it's available to all users on that machine (provided that the actual file location on the disk does not change). It's sometimes difficult to find a system administrator to register the plugin though. In this case we have provided a VBScript utility "register_wsc_hkcu.vbs" located in your install under <INSTALL DIR>\CodeSamples\Extend (where <INSTALL DIR> is typically C:\Program Files\AGI\ODTK 6 (32-bit Windows) or C:\Program Files (x86)\AGI\ODTK 6 (64-bit Windows)). The utility will register a Windows Script Component to the HKEY_CURRENT_USER area of the Windows registry rather than HKEY_LOCAL_MACHINE. To run the utility, open up a command prompt and change directories to the location of the utility. Then enter

cscript register_wsc_hkcu.vbs "Your WSC Name.wsc"

replacing "Your WSC Name.wsc" with the actual full path to the location of your Windows Script Component (WSC) file. The utility will parse your WSC file and make the appropriate entries into the Windows registry. This utility must be run for each user on the machine if they want to use that plugin.

NOTE: Before registering the components, if you have Microsoft AntiSpyware application actively running, you will have to perform one of the following tasks:

Windows Script Component Plugins

Components built as a Windows Script Component with a scripting environment (VBScript, JScript, Perl, Python) should have a filename extension 'wsc'. This is a XML text file declaring the implementation of the plugin interface. To register the component, create a command window (under the Start menu, hit "Run ...", type 'Command' and hit OK). Change your directory (using cd) to that of the file. At the command prompt, type 'regsvr32 YOUR_FILENAME'. For example:

regsvr32 VBScript.Example1.Hpop.wsc

Compiled Plugins built without using .NET

Compiled components are contained in a dynamic link library, whose filename has an extension 'dll'. To register the component, create a command window (under the Start menu, hit "Run ...", type 'Command' and hit OK). Change your directory (using cd) to that of the file. At the command prompt, type 'regsvr32 YOUR_FILENAME'. For example:

regsvr32 Agi.As.Hpop.Plugins.CPP.Examples.dll

Compiled Plugins built using .NET

Compiled components are contained in a dynamic link library, whose filename has an extension 'dll'. To register the component, create a command window (under the Start menu, hit "Run ...", type 'Command' and hit OK). Change your directory (using cd) to that of the file. At the command prompt, type 'regasm /codebase YOUR_FILENAME'. For example:

regasm /codebase Agi.As.Hpop.Plugin.CSharp.Examples.dll

NOTE: Your system may not recognize the regasm command. In that case, you will need to specify the full filepath to RegAsm.exe. The file itself is found in a sub-folder of C:\WINDOWS\Microsoft.NET\Framework\. The actual folder depends on your version of the .NET Framework installed on your machine.

Registration on 64-bit machines

When using regsvr32 on a 64-bit machine, it is important to know whether the COM object is built using a 32 or 64 bit architecture. In most cases, it is using 32 bits. To register a 32 bit built COM object, you must use the 32 bit version of regsvr32. Normally this is found in C:\Windows\SysWOW64. By default, 64 bit machines use the 64 bit version of regsvr32, so you should use

C:\Windows\SysWOW64\regsvr32.exe YOUR_FILENAME

when registering 32 bit COM objects. Currently, Windows Script Components are all 32 bit. COM objects written in PerlScript require an installation of 32-bit Perl software.

Registration with a Plugin Point (i.e. Category registration)

To register your plugin with ODTK, you need to list it in an XML registration file. You may choose to create a new XML file for each plugin you create; or you may choose to use one file to register multiple plugins (even multiple plugins to multiple categories). XML registration files located in {INSTALL_DIR}\Plugins will be available for every user; those located in {CONFIG_DIR}\Plugins will be available only for that user.

The registration file has the following form:

<?xml version = "1.0"?>
<AGIRegistry version = "1.0">
<Category Name = "Category Identifier 1">
<Plugin DisplayName = "Optional Display Name" ProgID = "ProgID of the Plugin 1"/>
<Plugin DisplayName = "Optional Display Name" ProgID = "ProgID of the Plugin 2"/>

<Category Name = "Category Identifier 2">

Each file is capable of registering multiple plugins (here shown using the <Plugin> tag) and registering multiple categories (here shown using the <Category> tag). You need not register all plugins of the same Category in the same file. The ProgID is the Program Identifier you chose to associate with your plugin's GUID. The Category Identifiers are names recognized by ODTK to identify each plugin point. Example XML registration files can be found in {INSTALL_DIR}\PluginSamples:

Plugin Type Category Name Example file
Engine Model Engine Models {INSTALL_DIR}\PluginSamples\ODTK\Gator\EngineModels\Engine Models.xml
Attitude Controller Attitude Controls {INSTALL_DIR}\PluginSamples\ODTK\Gator\AttitudeControllers\Attitude Controls.xml
Search Search {INSTALL_DIR}\PluginSamples\ODTK\Gator\Search\Search.xml
HPOP Force Model HPOP Plugins {INSTALL_DIR}\PluginSamples\ODTK\Hpop\ForceModels\Hpop Plugins.xml
Access Constraint Access Constraint Plugins {INSTALL_DIR}\PluginSamples\ODTK\Constraints\Access Constraints.xml

An example file is shown below for HPOP plugins:

<?xml version = "1.0"?>
<AGIRegistry version = "1.0">
<Category Name = "HPOP Plugins">
<Plugin DisplayName = "YOUR_DISPLAY_NAME" ProgID = "YOUR_PROGID"/>

NOTE: Tags (e.g., Plugin) and attributes (e.g., DisplayName) are case-sensitive.

The DisplayName is used as a user-friendly short-hand for the ProgID listed. You may choose any DisplayName you wish, but it should be unique amongst all registered plugins of the same category. See the sample registration files for the official category name of a plugin point.

When ODTK starts, it searches for xml files contained in identified folders and registers all plugins declared in each xml file found. Any changes made to these files after start-up will not take effect until the next time the application starts. ODTK looks at the following folders for xml plugin registration files:

NOTE: Previous ODTK versions used a Category Identifier (CAT_ID) to associate a given COM component with its intended Plugin Point in the Windows Registry. This is no longer necessary. The CAT_ID registration has been obsoleted in favor of the XML file registration.

Installation and Deployment

Once a plugin component has been built, it can be deployed to other machines for use by others. To do this, all the appropriate files (the wsc and script file for Windows Script Components, and all relevant dll files for compiled components) built with the plugin must be copied to the other machine. The plugin must be registered in the Windows registry and an appropriate xml registration file must be placed in a registration search folder.

NOTE: When you build a plugin in Debug mode, rather than Release mode, the component runs using Microsoft debug dynamic link libraries that are supplied with Visual Studio .NET. The plugin will not be able to run on a machine that does not have those Debug libraries. (Debug libraries are not redistributable and are not part of the standard Windows operating system installation.) In most cases, you should build a plugin for deployment to other machines using Release mode.

Using a Plugin Component

Once a plugin has been installed, a user can choose to use a plugin by selecting its ProgID or DisplayName from the user interface. The plugin may choose to declare certain parameters as being editable by the user. If so, then the user interface allows a user to edit these settings as well.

ODTK 6.5