- ==== CtrlProxy developer documentation ====
+CtrlProxy developer documentation
+=================================
Written by Jelmer Vernooij, 2003
+Updated October 2005
General
-------
-
+Here's what some of 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 would be:
-
-#include <ctrlproxy.h>
-
-gboolean init_plugin(struct plugin *p)
-{
- /* Do something */
- return TRUE;
-}
+is easily extendible.
-gboolean fini_plugin(struct plugin *p)
-{
- /* Free my structures here */
- return TRUE;
-}
+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
+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.
-The fini_plugin function is called before the module is unloaded.
-In this function, you should free the data structures your module is
-using and make sure there are no other pointers in ctrlproxy pointing
-to functions or data structures from your module. For example,
-unregister hooks.
-
-The fini_plugin should return a boolean as well. This value should be
-true if the unloading may preceed, or false if there are reasons
-ctrlproxy should not attempt to unload the module (such as resources
-that are currently in use, etc).
-
Building and installing
-----------------------
whenever ctrlproxy receives an IRC message. The only argument
this function should have would be a line struct.
-Flags can be set on the line (the field in the struct
-to use is called 'options') to influence the handling
-of the packet by the rest of ctrlproxy. At the time of writing,
-the following two flags are available:
-
-LINE_DONT_SEND
- Continue processing, but do not send this line.
-
-LINE_STOP_PROCESSING
- Immediately stop processing the line (passing it to other message handlers). Implemented as of version 2.5.
-
-LINE_NO_LOGGING
- Modules that do logging should ignore this line. This may be used for PRIVMSG's that are not interesting for logs, such as timestamps that are being printed.
-
-There is one other option that can be specified, but is only
-useful when sending your own messages:
-
-LINE_IS_PRIVATE
- Do not send this line to other clients currently connected.
-
Registering a message handler
-----------------------------
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
+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
-------------------------------------------------------------
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.
git.samba.org / jelmer / ctrlproxy.git / blobdiff