All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Turbulence Developer manual

Section 1: Creating turbulence modules (C language)

Section 2: Creating python apps (mod-python enabled)

Section 3: Vortex 1.1 API

Because Turbulence extends and it is built on top of Vortex Library 1.1, it is required to keep in mind and use Vortex API. Here is the reference:

Section 4: Turbulence API

The following is the API exposed to turbulence modules and tools. This is only useful for turbulence developers.

How Turbulence module works

Turbulence is a listener application built on top of Vortex Library, which reads a set of configuration files to start at some selected ports, etc, and then load all modules installed.

These modules could implement new BEEP profiles or features that extend Turbulence internal function.

Turbulence core is really small. The rest of features are added as modules. For example, Turbulence SASL support is a module which is configurable to use a particular user database and, with the help of some tools (tbc-sasl-conf), you can manage users that are allowed.

In fact, Turbulence know anything about SASL because this is delegated to mod-sasl. Turbulence SASL module installs and configures SASL profiles provided by Vortex, and using Profile Path (a Turbulence core feature), the security provisioning is meet.

Turbulence module form is fairly simple. It contains the following handlers (defined at TurbulenceModDef):

  1. Init (ModInitFunc): A handler called by Turbulence to start the module. Here the developer must place all calls required to install/configure a profile, init global variables, etc.

  2. Close (ModCloseFunc): Called by Turbulence to stop a module. Here the developer must stop and dealloc all resources used by its module.

  3. Reconf (ModReconfFunc): Called by Turbulence when a HUP signal is received. This is a notification that the module should reload its configuration files and start to behave as they propose.

  4. Profile path selected (ModPPathSelected): Called by Turbulence when the profile path for a connection was selected.

Creating a module from the scratch (dirty way)

Maybe the easiest way to start writing a Turbulence Module is to take a look into mod-test source code. This module does anything but is maintained across releases to contain all handlers required and a brief help. You can use it as an official reference. A module is at minimum composed by the following tree files:

Now if your intention is to built a BEEP profile then you should do all calls to install it and its associated handlers using the vortex profiles API at the Init (ModInitFunc) handler.

Using tbc-mod-gen to create the module (recommended)

This tool allows to create a XML template that is used to produce the module output. Here is an example:

First we create a xml empty module template:

>> mkdir template
>> cd template
>> tbc-mod-gen --template --enable-autoconf --out-dir .
I: producing a template definition at the location provided
I: creating file: ./template.xml
I: template created: OK

Now you should rename the file template.xml to something more appropriate and edit the template content, changing the module name and its description. Do not change the content of init, close and reconf nodes for now:

<mod-def>
   <name>mod-template</name>
   <description>Place here a generic module description</description>
   <source-code>
      <!--  init method, called once the module is loaded  -->
      <init><![CDATA[/* Place here your mod init code. This will be called once turbulence decides to include the module. */
return axl_true;]]></init>
      <!--  close method, called once the module is going to be stoped  -->
      <close><![CDATA[/* Place here the code required to stop and dealloc resources used by your module */]]></close>
      <!--  reconf method, called once it is received a 'reconfiguration signal'  -->
      <reconf><![CDATA[/* Place here all your optional reconf code if the HUP signal is received */]]></reconf>
      <!--  unload method, called once the module is required to be unloaded from memory due to child process creation (or similar)  -->
      <unload><![CDATA[/* Place here the code required to dealloc resources used by your module because turbulence signaled the child process must not have access */]]></unload>
      <!--  ppath_selected method, called once a profile path has been selected for a connection.  -->
      <ppath-selected><![CDATA[/* Place here the code to implement all provisioning that was deferred because non enough data was available at init method (connection and profile path selected) */
return axl_true;]]></ppath-selected>
   </source-code>
</mod-def>

Now, do the following to compile the content and produce a module that is compatible with the Turbulence interface, and it is full ready to be compiled and installed:

>> tbc-mod-gen --compile template.xml --out-dir . --enable-autoconf
I: creating file: ./mod_template.c
I: creating file: ./Makefile.am
I: found autoconf support files request..
I: creating file: ./autogen.sh
I: making executable: ./autogen.sh
I: creating file: ./configure.ac
I: creating file: ./gen-code
I: making executable: ./gen-code
I: mod_template created!

Now take a look into the files created, specially mod_template.c. Once you are ready, type the following to build the module:

>> ./autogen.sh
>> make
>> make install

If you are new to autotools, you have to now that the first command (autogen.sh) is only execute once. Next times you can run ./configure which have the same effect and run faster. The autogen.sh command is executed to bootstrap the project, adding all missing files.

Now you are ready to complete the module with your particular code. For that, you'll have to use the Turbulence API and specially the Vortex API. See document section for more details.