Merge fix for logging of mode changes by charly.
[jelmer/ctrlproxy.git] / 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.