$Id: ext_prog,v 2.1 2003/02/08 15:25:47 eric Exp $

Since the version 0.0.7, the hub has the ability to start external program.

I) Starting and existing program:
   ------------------------------

1) before trying to use external program, you must start the hub with the -e
   option followed by the directory containing runnable external program.

2) only Master of hub can start external program using the -startprg command
   followed by the program name (as in appears in the program directory).
   NOTE: you cannot have $, | or space in the progname because DC doesn't allow
   these characters.

3) If the program successfully starts, you will see a new user on the hub
   having the name of the program. Its connection type is "Bot". For the hub,
   it is a real user, this user is an operator.

4) now everything runs, the program can dialog with the hub as a normal user
   (operator), it will receive globat chat message, all queries and misc things
   a normal user can receive.


A sample of external program is provided in the extprog directory (dummy_prog).
This program simply prints message it receives on the terminal. 

5) The hub provides the capability to automatically start external programs.
   If a file named "AUTOSTART" exists in the external program directory, then,
   the file is read. Each line of this file is the name of an external program
   (w/o its path, like one for -start_prg command).

II) Building a new program:
    -----------------------

To simplify your live, I suggest you use dummy_prog as a base program. In the 
extprog directory of dchub, you have the source of this program and also sources
of basic IO communication functions (dc_com.c) and sources of premade commands
ready to be used (extprog_toolkit.c).

If you still want to build the program from scratch, here is some useful 
information:

* when the program is started by the hub, it receives 3 parameters:
  - its name (has it appears on the hub)
  - the number of the socket descriptor to use to communicate with the hub.
    This socket is an internet socket (AF_INET)
  - the IP of the host running the program (useful to search search and xfer).


There is not a lot to say about dialog data. The received and send commands are
and must be in DC format. Remember that the hub thinks the program at the other
end of its connection is a DC client. dummy_prog can easily help you by showing
you the kind/format of the received strings. To send command, you can look at 
DCTC source files (keyboard.c can be very useful) because dc_com is also part of
DCTC.

NOTE: despite the fact that the program must act like a normal client, you don't
      have to program the login stage. When the hub starts your program, it 
      has already performed this stage.
