src/modcmd.h

   1 /* modcmd.h - Generalized module command support
   2  * Copyright 2002-2006 srvx Development Team
   3  *
   4  * This file is part of srvx.
   5  *
   6  * srvx is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with srvx; if not, write to the Free Software Foundation,
  18  * Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.
  19  */
  20
  21 #if !defined(MODCMDS_H)
  22 #define MODCMDS_H
  23
  24 #include "recdb.h"
  25 #include "helpfile.h"
  26 #include "log.h"
  27
  28 struct service;
  29 struct svccmd;
  30 struct module;
  31 struct modcmd;
  32
  33 #define MODCMD_FUNC(NAME) int NAME(struct userNode *user, UNUSED_ARG(struct chanNode *channel), UNUSED_ARG(unsigned int argc), UNUSED_ARG(char **argv), UNUSED_ARG(struct svccmd *cmd))
  34 typedef MODCMD_FUNC(modcmd_func_t);
  35 #define SVCMSG_HOOK(NAME) int NAME(struct userNode *user, struct userNode *target, const char *text, int server_qualified)
  36 typedef SVCMSG_HOOK(svcmsg_hook_t);
  37
  38 DECLARE_LIST(svccmd_list, struct svccmd*);
  39 DECLARE_LIST(module_list, struct module*);
  40
  41 #if defined(GCC_VARMACROS)
  42 # define reply(ARGS...) send_message(user, cmd->parent->bot, ARGS)
  43 #elif defined(C99_VARMACROS)
  44 # define reply(...) send_message(user, cmd->parent->bot, __VA_ARGS__)
  45 #endif
  46
  47 #define modcmd_get_handle_info(USER, NAME) smart_get_handle_info(cmd->parent->bot, USER, NAME)
  48 #define modcmd_chanmode_announce(CHANGE) mod_chanmode_announce(cmd->parent->bot, channel, CHANGE)
  49 #define modcmd_chanmode(ARGV, ARGC, FLAGS) mod_chanmode(cmd->parent->bot, channel, ARGV, ARGC, FLAGS)
  50
  51 /* Miscellaneous flags controlling a command */
  52 #define MODCMD_DISABLED                  0x001
  53 #define MODCMD_NO_LOG                    0x002
  54 #define MODCMD_KEEP_BOUND                0x004
  55 #define MODCMD_ACCEPT_CHANNEL            0x008
  56 #define MODCMD_ACCEPT_PCHANNEL           0x010
  57 #define MODCMD_NO_DEFAULT_BIND           0x020
  58 #define MODCMD_LOG_HOSTMASK              0x040
  59 #define MODCMD_IGNORE_CSUSPEND           0x080
  60 #define MODCMD_NEVER_CSUSPEND            0x100
  61 /* Requirement (access control) flags */
  62 #define MODCMD_REQUIRE_AUTHED         0x001000
  63 #define MODCMD_REQUIRE_CHANNEL        0x002000
  64 #define MODCMD_REQUIRE_REGCHAN        0x004000
  65 #define MODCMD_REQUIRE_CHANUSER       0x008000
  66 #define MODCMD_REQUIRE_JOINABLE       0x010000
  67 #define MODCMD_REQUIRE_QUALIFIED      0x020000
  68 #define MODCMD_REQUIRE_OPER           0x040000
  69 #define MODCMD_REQUIRE_NETWORK_HELPER 0x080000
  70 #define MODCMD_REQUIRE_SUPPORT_HELPER 0x100000
  71 #define MODCMD_REQUIRE_HELPING        0x200000
  72 #define MODCMD_TOY                    0x400000
  73 #define MODCMD_REQUIRE_STAFF          (MODCMD_REQUIRE_OPER|MODCMD_REQUIRE_NETWORK_HELPER|MODCMD_REQUIRE_SUPPORT_HELPER)
  74
  75 #define SVCCMD_QUALIFIED              0x000001
  76 #define SVCCMD_DEBIT                  0x000002
  77 #define SVCCMD_NOISY                  0x000004
  78
  79 /* We do not use constants for 0 (no logging) and 1 (regular logging) as those
  80  * are used very often and are intuitive enough.
  81  */
  82 #define CMD_LOG_STAFF       0x02
  83 #define CMD_LOG_OVERRIDE    0x04
  84
  85 /* Modularized commands work like this:
  86  *
  87  * Modules define commands.  Services contain "bindings" of those
  88  * commands to names.
  89  *
  90  * The module-defined commands (modcmd structs) contain the parameters
  91  * fixed by code; for example, assuming a channel was provided, or
  92  * that the user has ChanServ access to that channel.
  93  *
  94  * Service command bindings (svccmd structs) define additional access
  95  * controls (and a count of how many times the command has been used)
  96  * as well as a link to the modcmd providing the function.
  97  *
  98  * Aliased commands are special svccmds that have alias expansion
  99  * information in an "extra" pointer.  In the future, this may be
 100  * moved into the svccmd struct if there are no other commands that
 101  * need "extra" data.
 102  *
 103  * The user must meet all the requirements (in flags, access levels,
 104  * etc.) before the command is executed.  As an exception, for the
 105  * "staff" permission checks (oper/network helper/support helper), any
 106  * one is sufficient to permit the command usage.
 107  */
 108
 109 struct service {
 110     struct userNode *bot;
 111     struct module_list modules;
 112     struct dict *commands; /* contains struct svccmd* */
 113     svcmsg_hook_t *msg_hook;
 114     unsigned int privileged : 1;
 115     char trigger;
 116 };
 117
 118 struct svccmd {
 119     char *name;
 120     struct service *parent; /* where is this command bound? */
 121     struct modcmd *command; /* what is the implementation? */
 122     struct string_list alias; /* if it's a complicated binding, what is the expansion? */
 123     unsigned int uses; /* how many times was this command used? */
 124     unsigned int flags;
 125     unsigned long req_account_flags;
 126     unsigned long deny_account_flags;
 127     unsigned int min_opserv_level;
 128     unsigned int min_staff_level;
 129     unsigned int min_channel_access;
 130     unsigned int effective_flags;
 131 };
 132
 133 struct module {
 134     char *name;                /* name of module */
 135     struct dict *commands;     /* contains struct modcmd* */
 136     struct log_type *clog;     /* where to send logged commands */
 137     const char *helpfile_name; /* name to use for helpfile */
 138     expand_func_t expand_help; /* expander function for helpfile */
 139     struct helpfile *helpfile; /* help file to use in case of syntax error */
 140 };
 141
 142 struct modcmd {
 143     char *name;
 144     struct module *parent;
 145     modcmd_func_t *func;
 146     struct svccmd *defaults;
 147     unsigned int min_argc;
 148     unsigned int flags;
 149     unsigned int bind_count;
 150 };
 151
 152 /* Register a command.  The varadic argument section consists of a set
 153  * of name/value pairs, where the name and value are strings that give
 154  * the default parameters for the command.  (The "flags" argument
 155  * gives the required parameters.)  The set is ended by a null name
 156  * pointer (without any value argument).
 157  */
 158 struct modcmd *modcmd_register(struct module *module, const char *name, modcmd_func_t func, unsigned int min_argc, unsigned int flags, ...);
 159
 160 /* Register a command-providing module.  clog is where to log loggable
 161  * commands (those without the MODCMD_NO_LOG flag and which succeed).
 162  */
 163 struct module *module_register(const char *name, struct log_type *clog, const char *helpfile_name, expand_func_t expand_help);
 164 /* Find a module by name.  Returns NULL if no such module is registered. */
 165 struct module *module_find(const char *name);
 166
 167 /* Register a command-using service. */
 168 struct service *service_register(struct userNode *bot);
 169 /* Find a service by name. */
 170 struct service *service_find(const char *name);
 171 /* Bind one command to a service. */
 172 struct svccmd *service_bind_modcmd(struct service *service, struct modcmd *cmd, const char *name);
 173
 174 /* Send help for a command to a user. */
 175 int svccmd_send_help(struct userNode *user, struct userNode *bot, struct svccmd *cmd);
 176 /* .. and if somebody doesn't have a modcmd handy .. */
 177 int svccmd_send_help_2(struct userNode *user, struct service *service, const char *topic);
 178 /* Check whether a user may invoke a command or not.  If they can,
 179  * return non-zero.  If they cannot (and noisy is non-zero), tell them
 180  * why not and return 0.
 181  */
 182 int svccmd_can_invoke(struct userNode *user, struct userNode *bot, struct svccmd *cmd, struct chanNode *channel, int flags);
 183 /* Execute a command.  Returns non-zero on success. */
 184 int svccmd_invoke_argv(struct userNode *user, struct service *service, struct chanNode *channel, unsigned int argc, char *argv[], unsigned int server_qualified);
 185 /* Get notification when a command is being unbound.  This lets
 186  * services which cache svccmd references remove them.
 187  */
 188 typedef void (*svccmd_unbind_func_t)(struct svccmd *target);
 189 void reg_svccmd_unbind_func(svccmd_unbind_func_t handler);
 190
 191 /* Initialize the module command subsystem. */
 192 void modcmd_init(void);
 193 /* Finalize the command mappings, read aliases, etc.  Do this after
 194  * all other modules have registered their commands.
 195  */
 196 void modcmd_finalize(void);
 197
 198 #endif /* !defined(MODCMDS_H) */