Writing Plugins Guide

Last updated: $Date: 2000/07/31 23:06:42 $

0. Preface
----------

ModLogAn stands for Modular Logfile Analyser. Modular means that the whole
program is divided into piece that are put together by some glue code.

0.1 The Glue code
-----------------
main.c		- main loop, history reading and writing
mconfig.c	- configfile reading, init of plugins
mdatatypes.c	- datatype handling
mhash.c		- hashing routines
misc.c		- conversion routines, strmatch
mlist.c		- double linked list
mlocale.c	- NLS support, country strings
mplugins.c	- plugin handling
mrecord.c	- framework for the record handling
mstate.c	- function to handle the internal state of modlogan

0.1.1 datatypes
---------------
mdatatypes.c, mlist.c, mhash.c are providing some datatype that unify and
simplify the data handling inside of modlogan.

mdatatypes.c provides the basic datatypes. every datatypes contains a block
called COMMON_DATA.

0.1.1.1 COMMON_DATA
-------------------

#define COMMON_DATA     \
        char *string;   \
        int count;      \
        int type;       \
        int (*destructor)(void *); \
        int (*write)(FILE *, void *); \
        int (*read)(void *, FILE *);\
        void* (*copy)(void *); \
        int (*append)(void *, void*);

'string' is the unique name of this element. most often it is the string
that is used later for the sorting. 
'count' is an integer that can be used to count the attemtes to insert an
element with same unique name (-> append function).
'type' is an integer that carries some options like GROUPING and so on.

'destructor' is a function that is called when the datatypes is removed from
memory. it takes care for the freeing of all by this datatype allocated
memory. 
'write' is used to put the datatype to the disk.
'read' reconstructs the datatype again.
'copy' is used to create a copy of the datatype.
'append' is called by mlist_insert() if the 'to be insert' datatype has the 
same unique name like this datatype. 

0.1.1.2 StrInt
--------------
The very basic datatype. It carries one string ('string') and one integer
('count'). (+ 'type')
It has 2 constructors:
data_StrInt *createStr2Int(char *str, int count, int type);
data_StrInt *createStrInt(char *str, int count); (deprecated)

append-function:
- adds the count to the already inserted count.

0.1.1.3 Str3Int
---------------
one string ('string'), 3 integers ('count', 'vcount', 'type').

constructors:
data_Str3Int    *createStr3Int(char *str, int count, int type, int vcount);

append function:
- adds the count to the already inserted count.
- adds the vcount to the already inserted vcount.

0.1.1.4 Visit
-------------

0.1.1.5 History
---------------


1. Input Plugin
---------------
An input plugins has to provide the following functions:

int mplugins_input_dlinit(mconfig *ext_conf);
int mplugins_input_dlclose(mconfig *ext_conf);
int mplugins_input_parse_config(mconfig *ext_conf, const char *key, 
  char *value);
int mplugins_input_set_defaults(mconfig *ext_conf);

int get_next_record(mconfig *ext_conf, mlogrec *record);

There has to be a file named 'parse.c'. This only improtant for the
configure script. It looks for this file and enables the selecting of this
plugin for the 'non-plugin' version.

2. Output Plugin
----------------
An output plugin has to provide the following function:

int mplugins_output_dlinit(mconfig *ext_conf);
int mplugins_output_dlclose(mconfig *ext_conf);
int mplugins_output_parse_config(mconfig *ext_conf, const char *key, 
  char *value);
int mplugins_output_set_defaults(mconfig *ext_conf);

int generate_monthly_output(mconfig *ext_conf, mstate *state);
int generate_history_output(mconfig *ext_conf, mlist *history);

There has to be a file named 'generate.c'. This only improtant for the
configure script. It looks for this file and enables the selecting of this
plugin for the 'non-plugin' version.

3. Processing Plugin
--------------------

int insert_record(mconfig *conf, mstate *state, mlogrec *record);