I. Perl script description.
   ------------------------

dchub can run a perl interpreter to support scripts. Use -d to define the
directory containing all the scripts and -s to define the first perl script
to load.

Note: if you use -d, you must also use -s (and vice-versa). If you don't use
      -d and -s, not perl interpreter is initialized (best solution if you
      don't want to use scripts).

* When the interpreter is loaded, dchub calls dchub_perl_init function to
  initialize somes values. Its parameters is the string provided with -d.

* Perl scripts are called when an event occurs. When some events occurs,
  dchub calls a function name dchub_perl_handler. This function
  receives a hash table (let's name it %evt_array) which contains the following
  entry:
  "event": it is the name of the occuring event
  "nickname": it is the name of the user who has generated the event (directly
         or not).
  "argc": it is the number of optional aguments provided.
         If optional arguments are provided, they are named "0","1","2","3", ...



II. Default scripts.
    ----------------

In the dchub package, there is a scripts directory which contains a file named 
main.pl

main.pl provides a generic dchub_perl_init and a generic dchub_perl_handler.
When the default dchub_perl_handler is called for an event XYZ, it tries to
call a function named dchub_XYZ_handler with %evt_array as parameter. If this
function does not exist, it tries to load from script_dir a file named
XYZ.pl. If the load fails, the handler ignores the event. On successful load,
another try to call dchub_XYZ_handler is performed. If the function still
does not exist, the handler ignores the event.


Note about loaded scripts: loaded scripts remains loaded in memory until
     the perl interpreter ends or is restarted. Thus, global variables exist
     with the same constraints.

III. List of defined events with their parameters
     --------------------------------------------

event name | argc | argument description
-----------+------+-------------------------------------------------------------
search     |  1   | the $Search query itself. Format of the query is described
           |      | in manage_cnx.c, function search_process
           |      | This event occurs when someone performs a query
-----------+------+-------------------------------------------------------------
unisearch  |  1   | the $UniSearch query itself. Format of the query is
           |      | described in manage_cnx.c, function unisearch_process
           |      | This event occurs when someone performs a query
-----------+------+-------------------------------------------------------------
myinfo     |  1   | the $MyINFO string itself. Format of the string is described
           |      | in manage_cnx.c, function myinfo_process
           |      | This event occurs when someone updates its personnal 
           |      | information (shared data size, e-mail, away/here).
-----------+------+-------------------------------------------------------------
getnicklist|  0   | This event occurs when someone retrieves the list of hub
           |      | users.
-----------+------+-------------------------------------------------------------
globalchat |  1   | the message itself (format: "<nick> message|"). 
           |      | This event occurs when someone sends a message on the public
           |      | chat
-----------+------+-------------------------------------------------------------
privchat   |  2   | 1st argument is the destination nickname
           |      | 2nd argument is the message content
           |      | This event occurs when someone sends a message on a private
           |      | chat
           |      | Note: message sent to Hub-Security doesn't generate this
           |      |       event.
-----------+------+-------------------------------------------------------------
revconnect |  2   | 1st argument is the destination nickname
           |      | 2nd argument is the RevConnecttome message
           |      | This event occurs when someone (A) wants to establish a 
           |      | connection with someone (B) else but (A) is a passive user.
-----------+------+-------------------------------------------------------------
connecttome|  2   | 1st argument is the destination nickname
           |      | 2nd argument is the ConnectToMe message
           |      | This event occurs when someone (A) wants to establish a 
           |      | connection with someone (B) else when (A) is an active user.
-----------+------+-------------------------------------------------------------
unknowncmd |  2   | 1st argument is the nickname generating this event
           |      | 2nd argument is the command
           |      | This event occurs when someone sends an unknown DC command
           |      | to the hub. Technically, using this command, it is possible
           |      | to support new custom commands.
-----------+------+-------------------------------------------------------------
quit       |  0   | this event occurs when a user leaves the hub.
-----------+------+-------------------------------------------------------------


IV. List of dchub functions available from perl scripts
    ---------------------------------------------------

few defines to simplify descriptions:
* a dcline is a line in the DCformat ie. it starts with a $ (except for global
  chat) and ends with a |
* nickname is the nickname of an user. Except if specified, the nickname doesn't
  have to belong to a user (valid).

a) generic output functions
   ------------------------

The following functions provide a generic interface to dchub output functions.
Technically, using these functions, you can send any DC commands you want to
anyone.

dchub::send_to_named_user( string nickname, string dcline)

    * send the given dcline to the user named nickname.

dchub::send_to_all_users( string dcline)

    * send the given dcline to all connected users.


b) dedicated chat functions
   ------------------------

dchub::send_gchat_msg( string sender_nickname, string message)

    * send a message on the global chat as user "sender_nickname". This function
      builds the appropriate DC message from the given information.

dchub::send_pchat_msg( string sender_nickname, string dest_nickname, string message)

    * send a private message as user "sender_nickname" to user "dest_nickname".
      This function builds the appropriate DC message from the given information.


c) misc functions
   --------------

dchub::disconnect(string nickname)

    * disconnect the user having the given nickname.

dchub::kick(string nickname)

    * same as disconnect but a kick message is displayed on the global chat.

dchub::forcemove(string nickname, string destination_address)

    * redirect the given user to the destination address

dchub::redirect(string nickname)

    * redirect the given user to "REDIR_ADDR".

dchub::redirectto(string nickname, string ip)

    * redirect the given user to the given address (ip).

dchub::userlist()

    * retrieve the list of hub users.

dchub::oplist()

    * retrieve the list of hub operators.

dchub::lstmultihubs()

    (N/A) retrieve the list of hubs linked with this hub.

dchub::nickinfo(string nickname)

    * retrieve information about the given nickname.
    The result string contains the following field and uses $ as field separator:
         + connection type
         + shared size
         + user e-mail
         + user description
         + user flag (bit 0: always set)
                     (bit 1: =0: user here, =1: user away)
                     (bit 2: =0: client is normal, =1, client is server ==online for more than 2 days)
                     (bit 3: =0: normal upload, =1: fast upload == upload speed greater than 100KB/s)
         + op flag   (==0: normal user)
                     (bit 0: =1: Operator privilege)
                     (bit 1: =1: Master privilege)
                     (bit 2: =1: Bot privilege)
                     (bit 3: =1: Fusion privilege)
                     (bit 4: =1: Hub privilege)
         + client version

dchub::nick_duration(string nickname)

    * return the number of seconds ellapsed since the beginning of this connexion
      This function is mainly useful when some events are periodic and when you don't want to
      reply to all of them (like the $MyINFO, only the first one should be useful at least to
      display "ok" messages).

dchub::nick_type(string nickname)

    * return the type of "account" used by the nickname. 
      This function returns "M" for hub master, "O" for operator, "N" for normal
      registered user and "U" for unregistered user.


d) hub configuration
   -----------------

dchub::get_max_users()

    * get the max number of users of the hub.

dchub::get_txtdescription()

    * get the hub description (for hub registration on DChublist)

dchub::get_hubip()

    * get the hub address (for hub registration on DChublist)


e) database access
   ---------------

dchub::db_get(string keyname)

    * get the value associated to the given key. The returned value is always a string

dchub::db_set(string keyname, keyvalue)

    * set the value associated to the given key. The key value can be an integer, a float or a string.



