From 64342a0d16c78f4ac98e0c83d92f1bf6d08d0db1 Mon Sep 17 00:00:00 2001 From: Bram Matthys Date: Sat, 26 Oct 2019 09:56:02 +0200 Subject: [PATCH] Document api-command.c and command API page. Change find_Command. (more in next commit) --- include/h.h | 3 +- src/api-command.c | 110 +++++++++++++++++++++++++++++++++------------- src/conf.c | 6 +-- src/ircd.c | 3 +- src/parse.c | 2 +- 5 files changed, 85 insertions(+), 39 deletions(-) diff --git a/include/h.h b/include/h.h index 63601380d..e9debc043 100644 --- a/include/h.h +++ b/include/h.h @@ -158,7 +158,7 @@ extern MODVAR struct list_head oper_list; extern MODVAR struct list_head unknown_list; extern MODVAR struct list_head global_server_list; extern MODVAR struct list_head dead_list; -extern RealCommand *find_Command(char *cmd, short token, int flags); +extern RealCommand *find_Command(char *cmd, int flags); extern RealCommand *find_Command_simple(char *cmd); extern Channel *find_channel(char *, Channel *); extern Membership *find_membership_link(Membership *lp, Channel *ptr); @@ -423,7 +423,6 @@ extern char *inetntop(int af, const void *in, char *local_dummy, size_t the_size /* Internal command stuff - not for modules */ extern MODVAR RealCommand *CommandHash[256]; extern void init_CommandHash(void); -extern RealCommand *add_Command_backend(char *cmd); /* CRULE */ char *crule_parse(char *); diff --git a/src/api-command.c b/src/api-command.c index f31f264b1..933433527 100644 --- a/src/api-command.c +++ b/src/api-command.c @@ -17,8 +17,21 @@ * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ +/** @file + * @brief Command API - both for modules and the core + */ #include "unrealircd.h" +/* Forward declarations */ +static Command *CommandAddInternal(Module *module, char *cmd, CmdFunc func, AliasCmdFunc aliasfunc, unsigned char params, int flags); +static RealCommand *add_Command_backend(char *cmd); + +/** @defgroup CommandAPI Command API + * @{ + */ + +/** Returns 1 if the specified command exists + */ int CommandExists(char *name) { RealCommand *p; @@ -32,7 +45,46 @@ int CommandExists(char *name) return 0; } -Command *CommandAddInternal(Module *module, char *cmd, CmdFunc func, AliasCmdFunc aliasfunc, unsigned char params, int flags) +/** Register a new command. + * @param module The module (usually modinfo->handle) + * @param cmd The command name (eg: "SOMECMD") + * @param func The command handler function + * @param params Number of parameters or MAXPARA + * @param flags Who may execute this command - one or more CMD_* flags + * @returns The newly registered command, or NULL in case of error (eg: already exist) + */ +Command *CommandAdd(Module *module, char *cmd, CmdFunc func, unsigned char params, int flags) +{ + if (flags & CMD_ALIAS) + { + config_error("Command '%s' used CommandAdd() to add a command alias, " + "but should have used AliasAdd() instead. " + "Old 3rd party module %s? Check for updates!", + cmd, + module ? module->header->name : ""); + return NULL; + } + return CommandAddInternal(module, cmd, func, NULL, params, flags); +} + +/** Register a new alias. + * @param module The module (usually modinfo->handle) + * @param cmd The alias name (eg: "SOMECMD") + * @param func The alias handler function + * @param params Number of parameters or MAXPARA + * @param flags Who may execute this command - one or more CMD_* flags + * @returns The newly registered command (alias), or NULL in case of error (eg: already exist) + */ +Command *AliasAdd(Module *module, char *cmd, AliasCmdFunc aliasfunc, unsigned char params, int flags) +{ + if (!(flags & CMD_ALIAS)) + flags |= CMD_ALIAS; + return CommandAddInternal(module, cmd, NULL, aliasfunc, params, flags); +} + +/** @} */ + +static Command *CommandAddInternal(Module *module, char *cmd, CmdFunc func, AliasCmdFunc aliasfunc, unsigned char params, int flags) { Command *command = NULL; RealCommand *c; @@ -74,27 +126,10 @@ Command *CommandAddInternal(Module *module, char *cmd, CmdFunc func, AliasCmdFun return command; } -Command *CommandAdd(Module *module, char *cmd, CmdFunc func, unsigned char params, int flags) -{ - if (flags & CMD_ALIAS) - { - config_error("Command '%s' used CommandAdd() to add a command alias, " - "but should have used AliasAdd() instead. " - "Old 3rd party module %s? Check for updates!", - cmd, - module ? module->header->name : ""); - return NULL; - } - return CommandAddInternal(module, cmd, func, NULL, params, flags); -} - -Command *AliasAdd(Module *module, char *cmd, AliasCmdFunc aliasfunc, unsigned char params, int flags) -{ - if (!(flags & CMD_ALIAS)) - flags |= CMD_ALIAS; - return CommandAddInternal(module, cmd, NULL, aliasfunc, params, flags); -} - +/** Delete a command - only used internally. + * @param command The command (can be NULL) + * @param cmd The "real" command + */ void CommandDelX(Command *command, RealCommand *cmd) { CommandOverride *ovr, *ovrnext; @@ -124,11 +159,18 @@ void CommandDelX(Command *command, RealCommand *cmd) safe_free(command); } +/** De-register a command - not called by modules, only internally. + * For modules this is done automatically. + */ void CommandDel(Command *command) { CommandDelX(command, command->cmd); } +/** @defgroup CommandAPI Command API + * @{ + */ + /** Calls the specified command for the user, as if it was received * that way on IRC. * @param client Client that is the source. @@ -156,12 +198,17 @@ void do_cmd(Client *client, MessageTag *mtags, char *cmd, int parc, char *parv[] (*cmptr->func) (client, mtags, parc, parv); } +/** @} */ + /**** This is the "real command" API ***** * Perhaps one day we will merge the two, if possible. */ RealCommand *CommandHash[256]; /* one per letter */ +/** Initialize the command API - executed on startup. + * This also registers some core functions. + */ void init_CommandHash(void) { memset(CommandHash, 0, sizeof(CommandHash)); @@ -177,7 +224,7 @@ void init_CommandHash(void) CommandAdd(NULL, MSG_MODULE, cmd_module, MAXPARA, CMD_USER); } -RealCommand *add_Command_backend(char *cmd) +static RealCommand *add_Command_backend(char *cmd) { RealCommand *c = safe_alloc(sizeof(RealCommand)); @@ -189,7 +236,12 @@ RealCommand *add_Command_backend(char *cmd) return c; } -static inline RealCommand *find_Cmd(char *cmd, int flags) +/** @defgroup CommandAPI Command API + * @{ + */ + +/** Find a command by name and flags */ +RealCommand *find_Command(char *cmd, int flags) { RealCommand *p; for (p = CommandHash[toupper(*cmd)]; p; p = p->next) { @@ -207,13 +259,7 @@ static inline RealCommand *find_Cmd(char *cmd, int flags) return NULL; } -RealCommand *find_Command(char *cmd, short token, int flags) -{ - Debug((DEBUG_NOTICE, "FindCommand %s", cmd)); - - return find_Cmd(cmd, flags); -} - +/** Find a command by name (no access rights check) */ RealCommand *find_Command_simple(char *cmd) { RealCommand *c; @@ -226,3 +272,5 @@ RealCommand *find_Command_simple(char *cmd) return NULL; } + +/** @} */ diff --git a/src/conf.c b/src/conf.c index 46d3c6011..d6e70979c 100644 --- a/src/conf.c +++ b/src/conf.c @@ -2361,7 +2361,7 @@ void config_rehash() safe_free(log_ptr); } for (alias_ptr = conf_alias; alias_ptr; alias_ptr = (ConfigItem_alias *)next) { - RealCommand *cmptr = find_Command(alias_ptr->alias, 0, 0); + RealCommand *cmptr = find_Command(alias_ptr->alias, 0); ConfigItem_alias_format *fmt; next = (ListStruct *)alias_ptr->next; safe_free(alias_ptr->nick); @@ -9064,7 +9064,7 @@ int _conf_alias(ConfigFile *conf, ConfigEntry *ce) ConfigEntry *cep, *cepp; RealCommand *cmptr; - if ((cmptr = find_Command(ce->ce_vardata, 0, CMD_ALIAS))) + if ((cmptr = find_Command(ce->ce_vardata, CMD_ALIAS))) CommandDelX(NULL, cmptr); if (find_Command_simple(ce->ce_vardata)) { @@ -9157,7 +9157,7 @@ int _test_alias(ConfigFile *conf, ConfigEntry *ce) { ce->ce_fileptr->cf_filename, ce->ce_varlinenum); errors++; } - else if (!find_Command(ce->ce_vardata, 0, CMD_ALIAS) && find_Command(ce->ce_vardata, 0, 0)) { + else if (!find_Command(ce->ce_vardata, CMD_ALIAS) && find_Command(ce->ce_vardata, 0)) { config_status("%s:%i: %s is an existing command, can not add alias", ce->ce_fileptr->cf_filename, ce->ce_varlinenum, ce->ce_vardata); errors++; diff --git a/src/ircd.c b/src/ircd.c index 15d0a3a5f..3f8525979 100644 --- a/src/ircd.c +++ b/src/ircd.c @@ -1260,8 +1260,7 @@ int InitUnrealIRCd(int argc, char *argv[]) umodes_check_for_changes(); charsys_check_for_changes(); clicap_init(); - if (!find_Command_simple("AWAY") /*|| !find_Command_simple("KILL") || - !find_Command_simple("OPER") || !find_Command_simple("PING")*/) + if (!find_Command_simple("PRIVMSG")) { config_error("Someone forgot to load modules with proper commands in them. READ THE DOCUMENTATION"); exit(-4); diff --git a/src/parse.c b/src/parse.c index 10f5b747e..0ae21b438 100644 --- a/src/parse.c +++ b/src/parse.c @@ -374,7 +374,7 @@ static void parse2(Client *cptr, Client **fromptr, MessageTag *mtags, char *ch) flags |= CMD_VIRUS; if (IsOper(from)) flags |= CMD_OPER; - cmptr = find_Command(ch, IsServer(cptr) ? 1 : 0, flags); + cmptr = find_Command(ch, flags); if (!cmptr || !(cmptr->flags & CMD_NOLAG)) { /* Add fake lag (doing this early in the code, so we don't forget) */