RageIRCd v2.0 (bluemoon): Custom Module API
-------------------------------------------

$Id: module-api.txt,v 1.6.2.1 2005/02/21 02:32:45 amcwilliam Exp $
(C) 2000-2005 the RageIRCd Development Team, all rights reserved.

RageIRCd v2.0 provides a dynamic framework for server admins and developers 
alike, to extend the functionality of ircd. (See doc/dynamic-modules.txt 
for more information.)

To develop a valid module, it must be compatible with the module 
subsystem available within RageIRCd v2.0. This document outlines the three 
mandatory objects required within a shared object in order to 
successfully load it into ircd.

The first required structure is the Module structure. This API is used to 
provide vital information about the module to the ircd server. This 
structure contains 4 variables: 2 strings, 1 integer, and 1 final string.

NB. All MOD_* symbol macros take a parameter, module_name. This should be a
short-hand module name, suitable for function names. E.g., the short-hand 
module_name for modules/commands/m_message.so would be "m_message".

Module MOD_HEADER(module_name) = {
	/* Specify the file name of the module, relative to INSTALL_PATH */
	"modules/module_name.so",
	/* Include a short description of the module. */
	"Module description",
	/* Specify the module API version number. For 2.0, this is version 6. */
	6,
	/* And finally the version of the module itself (e.g. CVS Revision). */
	"Module version"
};

NB. If your module needs to reference the information from within this 
structure, you can simply use the MOD_HEADER macro again. (The variables 
are below.) You can also use this macro to provide a pointer to the 
entire module header (i.e., if you're registering an object). Simply use 
&MOD_HEADER(module_name).

1. MOD_HEADER(module_name).name
2. MOD_HEADER(module_name).info
3. MOD_HEADER(module_name).version
4. MOD_HEADER(module_name).revision

Before the process of loading the module into the main memory, ircd will 
look for this structure. If it's not found, or if it fails validity 
checks, the module will fail to load.

The final two module symbols required by ircd are MOD_LOAD and MOD_UNLOAD. 
These are integer functions, called by ircd when the module is loading 
and unloading respectively.

MOD_LOAD is called when the module has been accepted, to setup any 
prerequisities the module may have. This function should return 
MOD_SUCCESS once successfully completed, or MOD_FAILURE if anything goes 
wrong. If MOD_FAILURE is returned, the module is aborted and will fail to 
load.

int MOD_LOAD(module_name)()
{
	if (something_is_wrong) {
		return MOD_FAILURE;
	}
	return MOD_SUCCESS;
}

MOD_UNLOAD is called when the module is being unloaded, to allow the 
module to "uninstall" itself, so to speak. As with MOD_LOAD, this function 
should return either MOD_SUCCESS on success, or MOD_FAILURE on failure. If 
MOD_FAILURE is returned, the module will not be unloaded.

int MOD_UNLOAD(module_name)()
{
	if (something_is_wrong) {
		return MOD_FAILURE;
	}
	return MOD_SUCCESS;
}

All objects defined within the main ircd source code are exported to 
modules automatically. However, your module may depend on an object from 
another module. Module subsystem 6, included from RageIRCd v2.0 beta-5, has 
the ability to find symbols for you, using the find_symbol() function. 
The syntax is below.

find_symbol(external_symbol, "modules/symbol_source_module.so")

The above example will search for "external_symbol." Should the symbol not 
currently exist, it will attempt to load modules/symbol_source_module.so. 
Provided the new module was loaded successfully, it will then attempt to 
resolve the symbol again. On error (for example, the symbol is not found), 
NULL is returned. Otherwise, a void* pointer to the symbol is returned.

End of document.
