Dev:Module

Below we will explain how to get started with writing a module. This article assumes you have experience with programming in the C language and that you are running UnrealIRCd 6.

Creating a new module

Create a new .c file in the directory src/modules/third. Be sure to use an unique name for your module.

Includes

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

#include "unrealircd.h"

Module Header

Every UnrealIRCd module has a special structure which is created by the macro MOD_HEADER. Simply add this to your module and fill in the appropriate values:

ModuleHeader MOD_HEADER
= {
        "mymodule", /* name */
        "1.0.0", /* version */
        "My custom command", /* description */
        "Anonymous author", /* author */
        "unrealircd-6", /* do not change this, it indicates module API version */
};

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;
}

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

Be advised that after MOD_TEST() was called, the module may be unloaded by UnrealIRCd if something fails. Therefore, normally you shouldn't allocate any structures in MOD_TEST.

MOD_INIT

This is called when the module is initialized. This is where most initialization happens: Hooks are registered here, as well as Events, Channel modes, User modes, etc.

MOD_INIT()
{
    /* Called on module initalization. Most module objects are added here: HookAdd()/CommandAdd()/EventAdd()/etc. */
    return MOD_SUCCESS;
}

MOD_LOAD

MOD_LOAD()
{
    /* Do necessary initialization for when module is loaded */
    /* For example: CommandOverrideAdd() */
    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, etc.

The MOD_LOAD() function is the place where you add command overrides (if you have any). Other than that, MOD_LOAD() is not used much, most goes into MOD_INIT() - see previous.

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). After that you can go to the Dev:Module API to actually make the module do something useful, for example via Hooks.

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-6.0.0$ cp /tmp/somemodule.c src/modules/third/
syzop@vulnscan:~/unrealircd-6.0.0$ make
syzop@vulnscan:~/unrealircd-6.0.0$ make install

Then, you can load the module and REHASH.