5 - The Logger Plug-in API

Table of Contents

• 5.1 Writing a Plug-In
• 5.2 Loading Plug-Ins

A plug-in is a dynamically linked module that is loaded by the Logger at runtime.

You can use plug-ins to modify the Logger executable. For example, you can change how the Logger processes packets, or you can override the Logger's DtLogger object with your own. While DtLogger is able to use plug-ins to extend functionality, the value of plug-ins is greater when using the existing Logger application, which has a plug-in interface for extending the application.

When you use a plug-in, all the basic functionality of the Logger application remains intact – command-line arguments are read and interpreted, user interfaces are created, and Logger control messages are intercepted. After all the normal initialization work, the application loads your plug-in and your changes take effect.

The Logger State Observer and lgrDump are examples of how to write a plug-in for the Data Logger application. They show the use of many techniques employed by the Logger API. The source code for the examples is in ./examples/stateObserver and ./examples/lgrDump.

5.1 Writing a Plug-In

All plug-in libraries must export a “C” style function, which will be recognized by the Logger executable when it loads the plug-in. A plug-in uses the following functions:

• void LoadPlugin()
• void UnloadPlugin()
• void EnableLoggerPlugin(DtLogger& logger)
• void EnableLoggerAppPlugin(DtLoggerApplication& app).

LoadPlugin() and UnloadPlugin() are required. They are called when a plug-in is loaded and unloaded. They can be used for allocation and deallocation of resources. Either EnableLoggerPlugin() or EnableLoggerAppPlugin() or both are required and are called after the DtLogger or DtLoggerApplication object is instantiated. Typically DtLogger plug-ins override existing classes and provide core functionality. DtLoggerApplication plug-ins extend the Logger application and can add additional functionality to the user-interface and extend the functionality of the application.

The following code example is from the State Observer plug-in (stateObserver.cxx):

extern "C" {
void LoadPlugin()
{   
}
void EnableLoggerPlugin(MAKLogger::DtLogger& logger)
{
   // Create controller 
   controller = new DtStateObserverController();
   // Create model
   model = new DtStateObserverModel(controller,logger.driver());
   // Add drive to Logger to handle commands.
   logger.driver().addDriver(DtStateObserverController::theCommandType,
   DtLgrCommandHandlerSP(model));
}
void EnableLoggerAppPlugin(MAKLogger::DtLoggerApplication& application)
{  
   DtLgrAppGui* gui = DtLgrAppGui::getQtGui(application);
   if(!gui)
   {
      DtLgrPrinter::errorMessage("Unable to get GUI.");
      return;
   }
   // Create view, must be done here after the gui is created.
   view = new DtStateObserverView(controller);
   controller->init(model,view);
   // Connect model to the sim state.
   model->connect(application.logger().simManager()->state());     
   // Add component to GUI.
   gui->addGuiComponent(view);
}
void UnloadPlugin()
{
   // No need to delete view, that is handled by the GUI
   // No need to delete model, that is handled by the system driver.
   delete controller;
} }

5.2 Loading Plug-Ins

The Logger looks for plug-ins in the location specified in lgrConfig.xml. A file is recognized as a plug-in library if it has the appropriate extension (.dll or .so) and can be loaded as a DLL or shared library.

The following is an example of configuring plug-ins in lgrConfig.xml:

<defaults>
...
<!-- -->
<!-- Library Modules -->
<!-- Do not add extension or 'd' if it is debug, these will be added -->
<!-- automatically. -->
<...
<var name="stateObserverPlugin" type="string" value="./stateObserver"></var>      
<var name="annotationPlugin" type="string" value="./lgrAnnotations"></var>
<!-- -->
...
</defaults>
<commands name="init">   
   <!-- Initialize commands executed after the command line is parsed -->
   ...
   <command domain="System" protocol="None" command="LoadPlugin">
      <param name="pluginName" var="annotationPlugin"></param>
   </command>
   <command domain="System" protocol="None" command="LoadPlugin">
      <param name="pluginName" var="stateObserverPlugin"></param>
   </command>
</commands>

You can also load plug-ins programmatically by sending the loadplugin command to the DtLogger.

The DtLogger can load a plug-in when it is sent the correct system command.

//Assume DtLogger* aLogger
DtCommand cmd = DtLgrSystemCommandFactory::createLoadPluginCommand(“stateOberver”);
aLogger->submitCommand(cmd);
aLogger->tick();

[<< Creating a Stand-Alone Logger Application] [Home] [Top of Page] [Logger API Coding Conventions >>]