How-To: Write a Plug-In (Part 1, The Basics)

Hi Everybody!

For the first part of my Plug-In tutorial, I am going to cover the basic overview of an elektra plug-in. This post just explains the basic format and functions of an Elektra plug-in, specifically a storage plug-in (this will be the focus of my tutorial).

All plug-ins use the same basic interface. This interface consists of five basic functions, elektraPluginOpen, elektraPluginGet, elektraPluginSet, elektraPluginError, and elektraPluginClose. The developer replaces ‘Plugin’ with the name of their plugin. So in the case of my plugin, the names of these functions would be elektraLineOpen(), elektraLineGet(), elektraLineSet(), elektraLineError(), and elektraLineClose(). Additionally, there is one more function called ELEKTRA_PLUGIN_EXPORT(plugin), where once again ‘Plugin” should be replaced with the name of the plug-in, this time in lower-case. So for my line plugin this function would be ELEKTRA_PLUGIN_EXPORT(line).

The KDB relies on the first five functions for interacting with configuration files stored in the key database.  Calls for kdbGet() and kdbClose() will call the functions elektraPluginGet() and elektraPluginClose() respectively for the plugin that was used to mount the configuration data. kdbSet() calls elektraPluginSet() but also elektraPluginError() when an error occurs. elektraPluginOpen() is called before the first call to elektraPluginGet() or elektraPluginSet(). These functions serve different purposes that allow the plug-in to work:

  • elektraPluginOpen() is designed to allow each plug-in to do initialization if necessary.
  • elektraPluginGet() is designed to turn information from a configuration file into a usable KeySet, this is technically the only function that is REQUIRED in a plug-in.
  • elektraPluginSet() is designed to store the information from the keyset back into a configuration file.
  • elektraPluginError() is designed to allow proper rollback of operations if needed and is called if any plugin fails during the set operation. This allows exception-safety.
  • elektraPluginClose() is used to free resources that might be required for the plug-in.
  • ELEKTRA_PLUGIN_EXPORT(Plugin) simply lets Elektra know that the plug-in exists and what the name of the above functions are.

Most simply put: most plug-ins consist of five major functions, elektraPluginOpen(), elektraPluginClose(), elektraPluginGet(), elektraPluginSet(), and ELEKTRA_EXPORT_PLUGIN(Plugin).

Because remembering all these functions can be cumbersome, we provide a skeleton plugin in order to easily create a new plugin. The skeleton plugin is called “template” and a new plugin can be created by calling the copy-template script. For example for my plugin I called

../../scripts/copy-template line

from within the plugins directory. Afterwards two important things are left to be done:

  1. remove all functions (and their exports) from the plugin that are not needed. For example not every plugin actually makes use of the elektraPluginOpen() function.
  2. provide a basic contract as described above

After these two steps your plugin is ready to be compiled, installed and mounted for the first time. Have a look at the mount tutorial for details on how to do this.

So Part 1 of the tutorial covers the implementation details for a plug-in. Next up will be Part 2, which will cover the theory behind contracts in Elektra as well as how to implement them.

Sincerely,
Ian S. Donnelly

2 thoughts on “How-To: Write a Plug-In (Part 1, The Basics)

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>