Dev:Command API

Registering a new command

Syntax:

Command *CommandAdd(Module *module, const char *cmd, CmdFunc func, unsigned char params, int flags);

• module - The module this command is associated with
• cmd - The text of the command
• func - A function pointer to be called when this function is executed (explained later)
• params - The number of parameters this command accepts, use MAXPARA to accept up to maximum.
• flags - The flags for this new command decide who may execute the command. Multiple flags are OR'ed together.

flags available:

Flag	Client type
CMD_USER	Fully registered client (user is online)
CMD_SERVER	A (trusted) server, such as another UnrealIRCd server or services.
CMD_UNREGISTERED	Unregistered client, this can later become a user or server but at this point is not fully registered yet. Be careful if you allow CMD_UNREGISTERED, because client->name may be empty and client->user and other pointers may be NULL, so it is easy to accidentally cause a crash.

Example:

CMD_FUNC(mymod_test); /* Forward declaration */

MOD_INIT(mymod)
{
    CommandAdd(modinfo->handle, "TEST", mymod_test, MAXPARA, CMD_USER|CMD_SERVER);
}

You should always add all your commands in MOD_INIT and never in MOD_LOAD.

The actual command function

Example:

CMD_FUNC(mymod_test)
{
    sendnotice(client, "Thanks for testing");
}

The CMD_FUNC() macro of UnrealIRCd will provide the following parameters:

Variable	Type	Description
client	Client *	Client pointer of user executing the command.
recv_mtags	MessageTag *	Message tags associated with the command. If you don't know what this is then just ignore it for now.
parc	int	Command + parameter count
parv	const char *[]	Parameters

Client information

For more information on the contents of client, see Common structures in the doxygen documentation. In particular, the Client struct documentation which shows you the meaning of all fields.

Parameter checking

Safe operation on parc and parv is important and may be slightly confusing if you're new. Here's an example: if you execute TEST lalala then parc will be 2 and parv[1] will contain the string lalala.

Most code in UnrealIRCd checks such things as follows:

CMD_FUNC(mymod_test)
{
    if ((parc < 3) || BadPtr(parv[2]))
    {
        sendnotice(client, "Error: Two parameter required");
        return;
    }
    sendnotice(client, "Thanks for testing with the following two parameter: '%s' and '%s'", parv[1], parv[2]);
}