src/modcmd.h

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