HACKING

   1                                 ==== CtrlProxy developer documentation ====
   2 Written by Jelmer Vernooij, 2003
   3 Updated October 2005
   4
   5 General
   6 -------
   7 The core of ctrlproxy is in the top source directory, standard module
   8 are in mods/.
   9
  10 Here's what the core files do:
  11
  12 cache.c - Caches and sends cached network state info
  13 client.c - Maintains connections to clients
  14 gen_config.c - Generates configuration file from current network state
  15 hooks.c - Handles calling hooks for various things (connect/disconnect/message)
  16 isupport.c - Maintains information about capabilities of server
  17 line.c - Parse / generate IRC messages
  18 linestack.c - Store lines / network state for later retrieval
  19 log.c - Logging
  20 main.c - main()
  21 network.c - Maintains connection to network
  22 plugins.c - Handles loading/unloading of plugins
  23 posix.c - POSIX support functions
  24 redirect.c - Send message received from server to the right clients
  25 repl.c - Replication support (sends JOIN/TOPIC messages to client from server state)
  26 settings.c - Configuration
  27 state.c - Maintains network state information (what users on which channel, etc)
  28 util.c - Random utility functions
  29
  30 Writing Modules
  31 ---------------
  32 As has been said in the introduction, ctrlproxy
  33 is easily extendible. At the time of writing, there
  34 are nine modules available.
  35
  36 The simplest possible module would be:
  37
  38 #include <ctrlproxy.h>
  39
  40 gboolean init_plugin(struct plugin *p)
  41 {
  42         /* Do something */
  43         return TRUE;
  44 }
  45
  46 The init_plugin function is called when the module is loaded.
  47 In this function, you should register whatever functions the module
  48 provides, such as a 'message handler' or a linestack backend. You
  49 can use the data member of the plugin struct to store data for your plugin.
  50 This function should return a boolean: false when initialisation failed
  51 or true when it succeeded.
  52
  53 Building and installing
  54 -----------------------
  55
  56 A module is in fact a shared library that's loaded
  57 at run-time, when the program is already running. The .so file can
  58 compiled with a command like:
  59
  60 $ gcc -shared -o foo.so input1.c input2.o input3.c
  61
  62 Message handler functions
  63 -------------------------
  64
  65 A message handling function is a function that is called
  66 whenever ctrlproxy receives an IRC message. The only argument
  67 this function should have would be a line struct.
  68
  69 Registering a message handler
  70 -----------------------------
  71
  72 All IRC lines that ctrlproxy receives and sends are passed thru
  73 so-called 'filter functions'. These functions can do things based on
  74 the contents of these lines, change the lines or stop further
  75 processing of these lines.
  76
  77 To add a filter function, call 'add_filter'. To remove the filter
  78 function again (usually when your plugin is being unloaded) call 'del_filter'.
  79
  80 Example:
  81
  82 ...
  83 add_filter("my_module", my_message_handler);
  84 ...
  85
  86 The prototype for the message handling function in the example
  87 above would look something like this:
  88
  89 static gboolean my_message_handler(struct line *l);
  90
  91 Your message handler should return TRUE if the rest of the filter
  92 functions should also see the message and FALSE if ctrlproxy should
  93 stop running filter functions on the given line struct.</para>
  94
  95 These hooks are executed before the data as returned by find_channel()
  96 and find_nick() is updated
  97
  98 Registering a new client/server or lose client/server handler
  99 -------------------------------------------------------------
 100
 101 A module can also register a function that should be called when a new
 102 client connects or when a client disconnects and when the server has successfully connected to
 103 the client or when the connection to the client is broken.</para>
 104
 105 typedef gboolean (*new_client_hook) (struct client *);
 106 typedef void (*lose_client_hook) (struct client *);
 107 void add_new_client_hook(char *name, new_client_hook h);
 108 void del_new_client_hook(char *name);
 109 void add_lose_client_hook(char *name, lose_client_hook h);
 110 void del_lose_client_hook(char *name);
 111
 112 typedef void (*server_connected_hook) (struct network *);
 113 typedef void (*server_disconnected_hook) (struct network *);
 114 void add_server_connected_hook(char *name, server_connected_hook);
 115 void del_server_connected_hook(char *name);
 116 void add_server_disconnected_hook(char *name, server_disconnected_hook);
 117 void del_server_disconnected_hook(char *name);
 118
 119 The prototypes of these functions pretty much speak for themselves.
 120 If a new_client_hook function returns FALSE, the client will be denied
 121 access.
 122
 123 Registering a initialization function
 124 -------------------------------------
 125
 126 The initialization hooks are called after ctrlproxy has been initialized -
 127 all plugins are loaded, all networks have been loaded.
 128
 129 typedef void (*initialized_hook) (void);
 130 void add_initialized_hook(initialized_hook);
 131
 132 Registering a MOTD function
 133 ---------------------------
 134
 135 MOTD functions are functions that add one or more lines to
 136 the MOTD that is sent to a client.
 137
 138 A module can register a MOTD function using the add_motd_hook() and
 139 del_motd_hook() functions, that work similar to the add_new_client_hook() and
 140 del_new_client_hook() functions documented above.
 141
 142 A motd function should return a dynamically allocated array containing
 143 dynamically allocated nul-terminated strings that should be added to the MOTD.
 144
 145 Log functionality
 146 -----------------
 147
 148 Ctrlproxy uses GLib's logging functions. Read the related section in the
 149 GLib documentation for details.
 150
 151 Storing data
 152 ------------
 153
 154 Paths to data should be configurable, but default to the file/directory name
 155 returned by ctrlproxy_path(). The argument to this function should be the
 156 name of the subsystem.
 157
 158 All top level directories have been created when this function
 159 returns.
 160
 161 If NULL was returned, one or more directories could not be created.
 162
 163 Debugging
 164 ---------
 165 Two very useful utilities are valgrind and gdb.
 166
 167 If you're running from gdb, make sure you have set the following:
 168
 169 handle SIGPIPE nostop
 170 handle SIGINT nostop
 171
 172 Debug module
 173 -------------
 174 The debug module, if compiled adds support for the following two admin commands,
 175 that might be useful when debugging:
 176
 177 DUMPJOINEDCHANNELS
 178         Makes ctrlproxy print a list of the channels it
 179         thinks it has joined on the current network.
 180
 181 CRASH
 182         Generates a crash.