LPuniversity Mudlib Documentation
---------------------------------

Title: Channel Daemon
Author: Tacitus @ LPuniversity
Date: 25-MAR-06
Revised: 30-JUN-08
Contributors: Tacitus, Tricky

---------------------------------

Contents:

 i. What is the channel daemon?
 ii. How does the LPUniversity channel daemon operate?
 iii. How-to: Create your own network module
 iv. Technical Documentation

 i. What is the channel daemon?

  The LPUniversity channel daemon allows for easier collaberation by providing
  a method of communication. How is communication different through the
  channel daemon? The channel daemon offers "channels" for specific discussion
  of a topic and these channels are usually accessible anywhere in the mud.
  Think of them as chat rooms.

  ii. How does the LPUniversity channel daemon operate?

  The channel daemon provided with the LPUniversity is different from most
  mud's becuase the LPUniversity channel daemon implements channels modularly.
  The LPUniversity channel daemon allows for the grouping of channels under
  "Networks". Each network is an actual object that handles the proccessing
  for all the channels in that network. This allows for different modules to
  be used depending on your needs and also allows for multiple networks to be
  easily implemented and used at the same time (ie. localNet and intermud3).

  You may be wondering what the actual channel daemon does then - Well, it
  acts a gate between the user and these network modules. The channel daemon
  will scan your input and parse input that if:

   a) A channel exists with the same name as the first word you entered
     (aka verb); and
   b) You are tuned into that channel.

  If the above criteria is met it will pass your input to the respective
  module.

  iii. How-to: Create your own network module

  As you already know, the LPUniversity channel daemon is very modular. If
  you'd like to create your own network module then continue to read.

  First off, you may ask: How do I implement xyz intermud protocol?

  The answer is this: Create a seperate object to manage the protocol and then
  implement the "channel" component of the intermud protocol into your network
  module. So, you'll have your network module acting as the middle man.

  Now, the network modules are possible because we use event-based
  programming. When an event occurs, the channel daemon will make a call to
  your network module and then you can make calls back to the channel daemon.

  The first call that needs to occur though is one from the module to the
  channel daemon to "register". This call will simply make the daemon aware of
  your module and allow for secure transmissions (secure as in no other module
  can tamper or intercept your calls). The code required to do this is as
  follows:

   CHAN_D->registerModule("INSERT_NETWORK_NAME_HERE", file_name(this_object()));

  After you have registered then you may register your channels. This can be
  accomplish by making the following call.

   CHAN_D->registerCh("INSERT_NETWORK_NAME_HERE", "INSERT_CHANNEL_HERE");

  If there is a channel already registered with that name then the following
  proccess will take place:

   a) If the channel is already registered and is registered by the module
      trying to register it again it will just drop the request (as there is
      no need).
   b) If the channel is already registered but another module is trying to
      register a channel with the same name then the channel daemon will
      rename it to the first three letters of the network, an underscore, then
      the original name following. The module will not know of this change as
      the channel daemon will keep note of the "real name" and will use it
      when communicating with the module.

  The following functions MUST exist in your network module

  int isAllowed(string user, string channel, int flag);
  int rec_m_msg(string channel, string originator, string msg);
  int rec_e_msg(string channel, string originator, string o_msg, string t_msg);
  int rec_t_msg(string channel, string originator, string target, string o_msg, string t_msg, string other_msg);

  The first function will be called by the daemon when a user attempts to
  tune/sign in or out of a channel. The first argument is the username of the
  user, next is the name of the channel, and finally the third is the flag
  (1 for in, 0 for out).

  The second function is called by the daemon when a user sends a message on a
  channel owned by your module. The first argument is the channel name, second
  is the name of the user and the third is the input.

  When the second function is called, rec_m_msg, you should:
   a) Send it to your router if your module is intermud; and
   b) send a formatted copy back to the daemon for all the other local
      listners. This can be accomplished by calling
      rec_m_msg(channel, originator, msg) in CHAN_D

      ex: CHAN_D->rec_m_msg(channel, originator, msg);

  The third function is called by the daemon when a user sends an emote on a
  channel owned by your module. The first argument is the channel name, second
  is the name of the user, third is the emote seen by the user and the fourth
  is the emote seen by all others.

  When the third function is called, rec_e_msg, you should:
   a) Send it to your router if your module is intermud; and
   b) send a formatted copy back to the daemon for all the other local
      listners. This can be accomplished by calling
      rec_e_msg(channel, originator, o_msg, t_msg) in CHAN_D

      ex: CHAN_D->rec_e_msg(channel, originator, o_msg, t_msg);

  The fourth function is called by the daemon when a user sends a targetted
  message on a channel owned by your module. The first argument is the channel
  name, second is the name of the user, third is the message seen by the user,
  fourth is the message seen by the target and the fifth is the message seen
  by everyone else.

  When the fourth function is called, rec_t_msg, you should:
   a) Send it to your router if your module is intermud; and
   b) send a formatted copy back to the daemon for all the other local
      listners. This can be accomplished by calling
      rec_t_msg(channel, originator, o_msg, t_msg, other_msg) in CHAN_D

      ex: CHAN_D->rec_t_msg(channel, originator, o_msg, t_msg, other_msg);

  And thats all there is to it! You might also want to add some commands like
  "/last" that will output history to the user. See localNet for example.

  iv. Technical Documentation

  This section will contain detailed information about each function.
  However, it is not written yet.
