How to create a new plugin for HSX
----------------------------------

* 3 functions must be provided by the plugin
  ------------------------------------------

proto v1.0
gchar *plugin_id(guint32 hsx_version_id);
      this function is called by HSX to identify the plugin.
      hsx_version_id is 0xABxxyyzz where xx is the plugin
      interface revision, 0x10 for revision 1.0, yy is HSX
      major version number and zz is HSX minor version number.
      Ex: HSX 3.28 support plugin interface revision 1.0,
          its ID will be 0xAB10031B
      If the plugin is able to deal with these versions, it
      should return a static string with its description.


proto v1.0
int plugin_load(char **ptr);
      this function is called when HSX loads the plugin
      (Note: when HSX calls plugin_id, it doesn't call
             plugin_load)
      This function must perform all necessary initializations
      like registring new task type, allocating memory, ...
      This function must return 0 on successful init and
      a positive number (>0) on failure. In case of failure,
      *ptr must be set to a static error message or NULL.


proto v1.0
int plugin_unload(char **ptr);
      this function is called when HSX unloads the plugin
      (Note: HSX calls plugin_unload only if plugin_load
             has previously succeded)
      This function must unregister previously declared task type,
      free memory, ...
      It should return 0 on successful end and a positive number
      (>0) on failure. In case of failure, *ptr must be set to
      a static error message or NULL.
      If this function returns -1, the plugin will never be 
      unloadable.

      
With this 3 functions, HSX can load a plugin.


======================================================================
======================================================================
======================================================================
* HSX usable functions
  --------------------

HSX provides some functions to the plugin. All these functions
are described in "module_base.h"


======================================================================
- Hotline task management

proto v1.0
int register_new_task_type(int type, void (*fnc)(int slot_num));
      This function registers a new Hotline task type. When data
      with this type are received, the function fnc will be called.
      This function returns 0 if type is accepted, 1 on out of 
      memory, 2 if type is already in table.

proto v1.0
void remove_task_type(int type)
      This function removes a Hotline task type.


======================================================================
- User socket management

Sometimes, a plugin must create pipes/sockets and manage them.
However, if the plugin performs long tasks or wait on socket,
whole HSX is hanged.
A solution is to tell HSX to watch to these sockets for the
plugin and to call a plugin function when ready.

proto v1.0
int register_new_user_socket(int socket_num, int flag, void (*fnc)(int socket_num, int flag));
      This function registers the socket socket_num inside
      HSX watch table. Flag is the waited event (Read/Write/Exception)
      and fnc is the function to call when the wanted event
      appears.

proto v1.0
void remove_user_socket(int socket_num,int flag);
      This function unregisters the socket socket_num of HSX watch table.


======================================================================
- Hotline dialog

When data matching a registered task type are received, you must
decode them and send a reply. Before describing functions, you must 
know how hotline builds its blocks. Read HL_PROTO file to find
information.

All the following functions are described in "module_hl_dialog.h"

proto v1.0
int get_hl_bloc_num(int slot_num);
      this function returns hotline block number. This number is
      necessary to send a reply to a client.
      WARNING: you must call this function before reply_block.

proto v1.0
int foreach_hlb_chunks(int slot_num,void *extra_param,
                      int (*generic_chunk_decoder)(int slot_num, void *extra_param,
                                                   guint32 chunk_type, guint32 chunk_len,
                                                   unsigned char *chunk));
      this function is called to decode a received hotline block.
      For each encountered chunk, it will call the function generic_chunk_decoder.
      This function is the main part of the hotline bloc decoder, you'd better
      read its prototype in the include file.


After data have been received, decoded and all is done, you must send a reply
to the client.

proto v1.0
void reply_block(int slot_num, int hl_bloc_num, guint32 type, guint32 flag, guint32 hc,...);
      Send a reply to a client. Read function prototype for more information.
      hl_bloc_num is the one obtained with get_hl_bloc_num.


======================================================================
======================================================================
======================================================================
Common bloc processing order
----------------------------

2 main type procedure is commonly encountered under hotline:
- basic 
- enhanced

1) basic

   This is the easiest method and all HL blocs can be supported using
   this method.

   a) you receive data (HSX calls you)
   b) you initialize your internal data structure
   c) you get hotline block number (=HBN)
   d) you tell HSX to decode chunk (foreach_hlb_chunks call)
   e) you do what you want to do
   f) you send a reply using previous HBN
   g) you free your internal data structure

   However, if your process takes more time, HSX hangs. On the other
   side, you don't have to take care about reentrant call. HSX is 
   only one process, when it is in your function, it is in your function.


2) enhanced

   Most file management (rm,rmdir,read dir) are performed using
   this method.

   a) you receive data (HSX calls you)
   b) you initialize your internal data structure
   c) you get hotline block number (=HBN)
   d) you create a sub process or a thread and create a pipe to talk
      with it.
   e) you register the pipe for reading (tell HSX to monitor this pipe)
   f) you send data to the sub process
   g) your function ends

   A) when your sub process write data inside the pipe, you can
      gather them and make a reply to the client using the appropriate
      HBN.
   B) Thus, you can free your internal data structure
 
