HACKING

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