RageIRCd v2.0 (bluemoon): User Mode API
---------------------------------------

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

RageIRCd v2.0 contains the XMODE (eXtended MODE) framework that is the footings
for the new dynamic channel and user mode subsystems. This framework allows
channel and user modes to be added at run-time through modules.

Please note: this document covers the user mode API to create new user modes,
NOT channel modes. RageIRCd v2.0 does not contain an API for channel modes, as
it required substantial recoding that would delay 2.0 further. As such, this
feature has been postponed until a future release -- such as 2.1.

Modules should create user modes through the following Module Objects API, not
internal commands from user_mode.c. This is to make sure that any created
objects are associated with thier proper owner. See module-objects.txt for
further information.

xMode* register_user_mode(Module* owner, char flag, long* mode,
    unsigned int options)

The above API will register mode `flag' with value `mode' in the user mode
subsystem. Additional per-mode options are specified by the `options' argument.
When called, a pointer to a new xMode entry will be returned on success, or
NULL on failure.

As with all Module Object APIs, the object owner should be specified by using
the MOD_HEADER macro. This is exmplained in the module-api.txt document.

It is worth mentioning that the mode argument is a pointer of type long. This
will be assigned the value of the mode as a bitmask. To define your user mode
flag, use the XMODE() macro. (See example below.)

Finally, the following user mode options are available.

    UOPT_LOCAL     - mode should not be recognised globally, but on a per-server
                     basis (such as +c and +f)
    UOPT_GLOBAL    - mode should be recognised globally (such as +o and +N)
    UOPT_NEEDOPER  - restricts user mode to operators only
    UOPT_AUTOOPER  - mode will be automatically set to everyone who /opers
    UOPT_SERVONLY  - mode can only be set by servers
    UOPT_ONCONNECT - modes automatically set on local-user connects

Due to the complexity of this API, an example is given below. The following code
creates user mode +B for bots.

XMODE(UMODE_BOT); /* This is our user mode */

int MOD_LOAD(bot_mode)
{
	xMode *mode_ptr = register_user_mode(&MOD_HEADER(bot_mode),
			'B',			/* the user mode flag is +B */
			&UMODE_BOT,		/* pointer to the user mode itself */
			UOPT_GLOBAL		/* transmit the mode on netburst etc. */
		);
	
	if (mode_ptr == NULL) {
		return MOD_FAILURE;
	}
	
	return MOD_SUCCESS;
}

From here you can now use the HasMode(), AddMode() and DelMode() macros with
UMODE_BOT as normal. For example:

    if (!HasMode(client_ptr, UMODE_BOT))
    {
        ...
    }

End of document.
