File: HACKING

package info (click to toggle)
ctrlproxy 3.0.7-1
  • links: PTS
  • area: main
  • in suites: lenny, squeeze
  • size: 1,668 kB
  • ctags: 2,045
  • sloc: ansic: 15,358; sh: 2,805; xml: 1,078; python: 346; makefile: 302; perl: 18
file content (176 lines) | stat: -rw-r--r-- 6,112 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
CtrlProxy developer documentation
=================================
Written by Jelmer Vernooij, 2003
Updated October 2005

General
-------
The core of ctrlproxy is in the top source directory, standard module
are in mods/.

Here's what the core files do:

cache.c - Caches and sends cached network state info
client.c - Maintains connections to clients
gen_config.c - Generates configuration file from current network state
hooks.c - Handles calling hooks for various things (connect/disconnect/message)
isupport.c - Maintains information about capabilities of server
line.c - Parse / generate IRC messages
linestack.c - Store lines / network state for later retrieval
log.c - Logging
main.c - main()
network.c - Maintains connection to network
plugins.c - Handles loading/unloading of plugins
posix.c - POSIX support functions
redirect.c - Send message received from server to the right clients
repl.c - Replication support (sends JOIN/TOPIC messages to client from server state)
settings.c - Configuration
state.c - Maintains network state information (what users on which channel, etc)
util.c - Random utility functions

Writing Modules
---------------
As has been said in the introduction, ctrlproxy 
is easily extendible. At the time of writing, there 
are nine modules available.

The simplest possible module can be found in example/foo.c in the source 
distribution.

The init_plugin function is called when the module is loaded. 
In this function, you should register whatever functions the module 
provides, such as a 'message handler' or a linestack backend. You 
can use the data member of the plugin struct to store data for your plugin. 
This function should return a boolean: false when initialisation failed 
or true when it succeeded.

Building and installing
-----------------------

A module is in fact a shared library that's loaded 
at run-time, when the program is already running. The .so file can 
compiled with a command like:

$ gcc -shared -o foo.so input1.c input2.o input3.c

Message handler functions
-------------------------

A message handling function is a function that is called 
whenever ctrlproxy receives an IRC message. The only argument 
this function should have would be a line struct. 

Registering a message handler
-----------------------------

All IRC lines that ctrlproxy receives and sends are passed thru 
so-called 'filter functions'. These functions can do things based on 
the contents of these lines, change the lines or stop further 
processing of these lines. 

To add a filter function, call 'add_filter'. To remove the filter 
function again (usually when your plugin is being unloaded) call 'del_filter'.

Example:

...
add_filter("my_module", my_message_handler);
...

The prototype for the message handling function in the example 
above would look something like this:

static gboolean my_message_handler(struct line *l);

Your message handler should return TRUE if the rest of the filter 
functions should also see the message and FALSE if ctrlproxy should 
stop running filter functions on the given line struct.</para>

These hooks are executed before the data as returned by find_channel() 
and find_nick() is updated

Registering a new client/server or lose client/server handler
-------------------------------------------------------------

A module can also register a function that should be called when a new 
client connects or when a client disconnects and when the server has successfully connected to 
the client or when the connection to the client is broken.</para>

typedef gboolean (*new_client_hook) (struct client *);
typedef void (*lose_client_hook) (struct client *);
void add_new_client_hook(char *name, new_client_hook h);
void del_new_client_hook(char *name);
void add_lose_client_hook(char *name, lose_client_hook h);
void del_lose_client_hook(char *name);

typedef void (*server_connected_hook) (struct network *);
typedef void (*server_disconnected_hook) (struct network *);
void add_server_connected_hook(char *name, server_connected_hook);
void del_server_connected_hook(char *name);
void add_server_disconnected_hook(char *name, server_disconnected_hook);
void del_server_disconnected_hook(char *name);

The prototypes of these functions pretty much speak for themselves. 
If a new_client_hook function returns FALSE, the client will be denied 
access.

Registering a initialization function
-------------------------------------

The initialization hooks are called after ctrlproxy has been initialized - 
all plugins are loaded, all networks have been loaded.

typedef void (*initialized_hook) (void);
void add_initialized_hook(initialized_hook);

Registering a MOTD function
---------------------------

MOTD functions are functions that add one or more lines to 
the MOTD that is sent to a client.

A module can register a MOTD function using the add_motd_hook() and 
del_motd_hook() functions, that work similar to the add_new_client_hook() and 
del_new_client_hook() functions documented above.

A motd function should return a dynamically allocated array containing 
dynamically allocated nul-terminated strings that should be added to the MOTD.

Log functionality
-----------------

Ctrlproxy uses GLib's logging functions. Read the related section in the 
GLib documentation for details.

Storing data
------------

Paths to data should be configurable, but default to the file/directory name 
returned by ctrlproxy_path(). The argument to this function should be the 
name of the subsystem.
	
All top level directories have been created when this function 
returns. 

If NULL was returned, one or more directories could not be created.

Debugging
---------
Two very useful utilities are valgrind and gdb. 

If you're running from gdb, make sure you have set the following: 

handle SIGPIPE nostop
handle SIGINT nostop

Debug module
-------------
The debug module, if compiled adds support for the following two admin commands,
that might be useful when debugging:

DUMPJOINEDCHANNELS
	Makes ctrlproxy print a list of the channels it 
	thinks it has joined on the current network.

CRASH
	Generates a crash.