apps/irssi/docs/design.txt

   1
   2  Irssi's hierarchy is something like this:
   3
   4
   5          sub1 sub2
   6             \ /
   7        xxx  IRC       COMMON ICQ  yyy
   8         |____|___________|____|____|
   9                    |
  10                   GUI (gtk/gnome, qt/kde, text, none)
  11                    |
  12          sub1 sub2 |
  13             \ /    |
  14        xxx  IRC    |  COMMON ICQ  yyy
  15         |____|_____|_____|____|____|
  16                    |
  17                COMMON UI
  18                    |
  19          sub1 sub2 |
  20             \ /    |
  21        xxx  IRC    |    ICQ  yyy
  22         |____|_____|_____|____|
  23                    |
  24                  CORE
  25                  /  \
  26         lib-config  lib-popt
  27
  28
  29  (IRC, ICQ, xxx and yyy are chat protocols ..)
  30  (sub1 and sub2 are submodules of IRC module, like DCC and flood protect)
  31
  32
  33  Chat protocols and frontends are kept in separate modules. Common UI
  34  and GUI modules also have the common parts which don't know anything
  35  about the chat protocols. This should allow implementing modules to
  36  whatever chat protocols and with whatever frontends easily.
  37
  38  ** Signals
  39
  40  Communication between different modules are done with "signals". They are
  41  not related to UNIX signals in any way, you could more like think of them
  42  as "events" - which might be a better name for them, but I don't really
  43  want to change it anymore :)
  44
  45  So, you send signal with signal_emit() and it's sent to all modules that
  46  have grabbed it by calling signal_add() in their init function. For
  47  example:
  48
  49    signal_emit("mysignal", 1, "hello");
  50
  51  Sends a "mysignal" function with one argument "hello" - before that, you
  52  should have grabbed the signal somewhere else with:
  53
  54    static void sig_mysignal(const char *arg1)
  55    {
  56      /* arg1 contains "hello" */
  57    }
  58
  59    signal_add("mysignal", (SIGNAL_FUNC) sig_mysignal);
  60
  61  There are three different signal_add() functions which you can use to
  62  specify if you want to grab the signal first, "normally" or last. You can
  63  also stop the signal from going any further.
  64
  65  Emitting signal with it's name creates a small overhead since it has to
  66  look up the signal's numeric ID first, after which it looks up the signal
  67  structure. This is done because if you call a signal _really_ often,
  68  it's faster to find it with it's numeric ID instead of the string. You
  69  can use signal_get_uniq_id() macro to convert the signal name into ID -
  70  you'll have to do this only once! - and use signal_emit_id() to emit the
  71  signal. Don't bother to do this unless your signal is sent (or could be
  72  sent) several times in a second.
  73
  74  See src/core/signals.h for defination of the signal function, and
  75  signals.txt for a list of signals.
  76
  77
  78  ** lib-popt
  79
  80    CORE depends on this for command line parameter handling.
  81    (distributed with irssi)
  82
  83
  84  ** lib-config
  85
  86    Irssi depends on this for reading and saving configuration.
  87    (created by me for irssi)
  88
  89
  90  ** CORE module
  91
  92  Provides some functionality that all other modules can use:
  93    - signal handling
  94    - keeping list of settings
  95    - keeping list of /commands
  96    - keeping track of loaded modules
  97    - networking functions (with nonblocking connects, IPv6 support)
  98    - handles connecting to servers
  99    - raw logging of server's input/output data
 100    - /EVAL support
 101    - fgets() like function line_split() without any maximum line limits
 102    - command line parameter handling
 103    - miscellaneous useful little functions
 104    - handles logging
 105
 106
 107  ** COMMON UI module
 108
 109    - knows basics about windows and window items (=channels, queries, ..)
 110    - printtext() - parsing texts and feeding it for GUI to print.
 111    - themes
 112    - translation tables
 113    - text hilighting
 114    - command history
 115    - user interface (/commands) for CORE's functionality
 116
 117
 118  ** GUI modules
 119
 120    - all the rest of the functionality needed for a working client.
 121
 122
 123  ** IRC module
 124
 125    * CORE
 126
 127      - IRC specific /commands
 128      - flood protecting commands sent to server
 129      - creating IRC masks based on nick/address for bans, ignores, etc.
 130      - keeps list of channels, nicks, channel modes, bans, etc.
 131      - keeps list of servers, server settings, irc networks,
 132        server reconnections and irc network splits
 133      - redirection of commands' replies
 134      - lag detection
 135      - ctcp support and flood protection
 136      - Handles ignoring people
 137
 138    * DCC
 139
 140      - DCC chat, send and get
 141
 142    * FLOOD
 143
 144      - detects private or channel flooding and sends "flood" signal
 145      - automatic ignoring when flooding
 146
 147    * NOTIFYLIST
 148
 149      - handles notifylist
 150
 151
 152  ** IRC UI module
 153
 154    - placing channels and queries in windows
 155    - nick completion
 156    - printing infomation of some events