Dev:Module

Below we will explain why modules are useful and how to get started with writing a module, step by step. This article assumes you are developing for UnrealIRCd 5.x.

= Why Modules? =

Within UnrealIRCd, a large amount of functionality is provided via modules. A modular design has many advantages, including:


 * Permits easier selection of features for networks/users that may not want certain functionality present
 * Allows less hassle for upgrades by permitting all but the core functionality to be updated and reloaded independently of the main IRCd
 * Makes code more maintainable by decoupling components and enforcing a strict separation of concerns
 * Eases third party contributions through making the code more approachable.

To this end, if you’re just starting to contribute, modules are generally the place to get started.

= Creating a new module =

Includes
Your module should start by including "unrealircd.h":


 * 1) include "unrealircd.h"

Module Header
Every UnrealIRCd module has a special structure which is created by the macro MOD_HEADER. This includes the name of the module, the version, a description, a modversion, and a symbol table that is generally NULL.

ModuleHeader MOD_HEADER = {       "mymodule", /* name */ "1.0.0", /* version */ "My custom command", /* description */ "Anonymous author", /* author */ "unrealircd-5", /* this needs to be this value */ };

Module Functions
For the module to actually do something there are MOD_XXX functions that will be called on test, init, load and unload.

These functions are generally the place where module authors will hook into UnrealIRCd's Dev:Module API and perform any cleanup if necessary.

MOD_TEST
This function is executed when the module has just been loaded. If you want to run configuration test hooks (like HOOKTYPE_CONFIGTEST and HOOKTYPE_CONFIGPOSTTEST) then you add them here. Otherwise, simply don't add a MOD_TEST function.

MOD_TEST {   /* Test here */ return MOD_SUCCESS; }

After your MOD_TEST function is called (and callbacks set up there being called) your module COULD be unloaded by UnrealIRCd. This would be the case if your module, or any other module, fails config tests. So normally you shouldn't allocate any structures in MOD_TEST.

Note that MOD_TEST is really just for running config tests and not for anything else. All the other initialization should go in MOD_INIT, see next.

MOD_INIT
This function is executed when the module is loaded and is responsible for doing any initial structure initialization. Hooks and callbacks are registered here, as well as registering channel and user modes.

MOD_INIT {   /* Initialization here */ return MOD_SUCCESS; }

Please keep in mind that this method should make no assumptions about the surrounding state when it is loaded: the server may have active users and channels, or it may have just been started. The module can safely assume that the system can register hooks, channel modes, user modes, structures, etc, but no other assumptions can be made safely.

MOD_LOAD
MOD_LOAD {   // Do necessary initialization for when module is loaded return MOD_SUCCESS; /* returning anything else is not really supported here */ }

The MOD_LOAD function is called when the module is fully loaded, configuration has been read (if any). All commands and user/channel modes etc. have been loaded at this point. The MOD_LOAD function is the place where you add command overrides (if you have any).

MOD_UNLOAD
MOD_UNLOAD {	// Perform any cleanup for unload return MOD_SUCCESS; }

The MOD_UNLOAD operation is called by the system when a module is being unloaded. Note that structures created by the UnrealIRCd API such as channel modes, user modes, etc. are all cleaned up automatically. You should (only!) do cleanup of internal structures such as freeing internal memory structures, closing handles (eg: files, curl, etc).

Adding commands, user modes, overrides, hook, etc..
Now you have your module skeleton, you can test compile it (see below) or go straight to Dev:Module API to actually make the module do something useful.

= Compiling modules = In your UnrealIRCd source directory put the .c file in the src/modules/third directory. Then just run 'make'. UnrealIRCd will automatically detect the 3rd party modules in that directory and compile them. syzop@vulnscan:~/unrealircd-5.0.0$ cp /tmp/somemodule.c src/modules/third/ syzop@vulnscan:~/unrealircd-5.0.0$ make