$Id: scripts,v 2.7 2003/05/13 19:44:54 blusseau Exp $

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 every functions which are "bind" to the XYZ event with %evt_array as parameter.
To "bind" a function to a handler you need to create a perl script and "source" it
in the dchub_scripts.conf file (which is in the scripts directory).
In the perl script you have to add a call to the add_hook function to really "bind"
your function to the handler.

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 |params | argument description
-----------+-------+-------------------------------------------------------------
search     |   1   | This event occurs when someone performs a query
           |       | parameter 1: evt_array (see main.pl for explanation)
           |       |  - $evt_array->{0} : the $Search query itself.
           |       |        Format of the query is described in manage_cnx.c,
           |       |        function search_process
-----------+-------+-------------------------------------------------------------
unisearch  |   1   | This event occurs when someone performs a query
           |       | parameter 1: evt_array (see main.pl for explanation)
           |       |  - $evt_array->{0}: the $UniSearch query itself.
           |       |        Format of the query is described in manage_cnx.c,
           |       |        function unisearch_process
-----------+-------+-------------------------------------------------------------
myinfo     |   1   | This event occurs when someone updates its personnal 
           |       | information (shared data size, e-mail, away/here).
           |       | parameter 1: evt_array (see main.pl for explanation)
           |       |  - $evt_array->{0} : the $MyINFO string itself.
           |       |        Format of the string is described in manage_cnx.c,
           |       |        function myinfo_process
-----------+-------+-------------------------------------------------------------
getnicklist|   1   | This event occurs when someone retrieves the list of hub
           |       | users.
           |       | parameter 1: evt_array (see main.pl for explanation)
-----------+-------+-------------------------------------------------------------
globalchat |   3   | This event occurs when someone sends a message on the public chat.
           |       | parameter 1: evt_array (see main.pl for explanation)
           |       |  - $evt_array->{0} : The message itself (format: "<nick> message|"). 
           |       | parameter 2: nickname of the message sender
           |       | parameter 3: unescape message without the trailing |
-----------+-------+-------------------------------------------------------------
privchat   |   4   | This event occurs when someone sends a message on a private chat.
           |       | parameter 1: evt_array (see main.pl for explanation)
           |       |  - $evt_array->{0} : is the destination nickname
           |       |  - $evt_array->{1} : is the message content
           |       | parameter 2: nickname of the sender
           |       | parameter 3: nickname of the receiver
           |       | parameter 4: unescape message without the trailing |
           |       | Note: message sent to Hub-Security doesn't generate this
           |       |       event.
-----------+-------+-------------------------------------------------------------
revconnect |   1   | This event occurs when someone (A) wants to establish a 
           |       | connection with someone (B) else but (A) is a passive user.
           |       | parameter 1: evt_array (see main.pl for explanation)
           |       |  - $evt_array->{0} : is the destination nickname
           |       |  - $evt_array->{1} : is the RevConnecttome message
-----------+-------+-------------------------------------------------------------
connecttome|   1   | This event occurs when someone (A) wants to establish a 
           |       | connection with someone (B) else when (A) is an active user.
           |       | parameter 1: evt_array (see main.pl for explanation)
           |       |  - $evt_array->{0} : is the destination nickname
           |       |  - $evt_array->{1} : is the ConnectToMe message
-----------+-------+-------------------------------------------------------------
unknowncmd |   2   | 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.
           |       | parameter 1: evt_array (see main.pl for explanation)
           |       |  - $evt_array->{0} : is the nickname generating this event
           |       |  - $evt_array->{1} : is the command
-----------+-------+-------------------------------------------------------------
quit       |   1   | This event occurs when a user leaves the hub.
           |       | parameter 1: evt_array (see main.pl for explanation)
-----------+-------+-------------------------------------------------------------
login      |   1   | This event occurs when a user enters the hub.
           |       | parameter 1: evt_array (see main.pl for explanation)
           |       |  - $evt_array->{0} : the argument is a string containing the
           |       |                     IP of the new user
-----------+-------+-------------------------------------------------------------


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: unused)
                     (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 VIP user, "b" for hub bot, "B" for hub master bot and
      "U" for unregistered user.

dchub::hubcmd(string nickname, string hub_command)

    * process the given hub_command (a command starting with a '-') as if it was
      sent by the user 'nickname' to 'Hub-Security' private chat.


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.
