include/mode.h

   1 /*       +------------------------------------+
   2  *       | Inspire Internet Relay Chat Daemon |
   3  *       +------------------------------------+
   4  *
   5  *  InspIRCd is copyright (C) 2002-2006 ChatSpike-Dev.
   6  *                       E-mail:
   7  *                <brain@chatspike.net>
   8  *                <Craig@chatspike.net>
   9  *
  10  * Written by Craig Edwards, Craig McLure, and others.
  11  * This program is free but copyrighted software; see
  12  *            the file COPYING for details.
  13  *
  14  * ---------------------------------------------------
  15  */
  16
  17 #ifndef __MODE_H
  18 #define __MODE_H
  19
  20 /* include the common header files */
  21 #include <typeinfo>
  22 #include <iostream>
  23 #include <string>
  24 #include <deque>
  25 #include <sstream>
  26 #include <vector>
  27 #include "users.h"
  28 #include "channels.h"
  29 #include "ctables.h"
  30
  31 /**
  32  * Holds the values for different type of modes
  33  * that can exist, USER or CHANNEL type.
  34  */
  35 enum ModeType {
  36         MODETYPE_USER = 0,
  37         MODETYPE_CHANNEL = 1
  38 };
  39
  40 /**
  41  * Holds mode actions - modes can be allowed or denied.
  42  */
  43 enum ModeAction {
  44         MODEACTION_DENY = 0, /* Drop the mode change, AND a parameter if its a parameterized mode */
  45         MODEACTION_ALLOW = 1 /* Allow the mode */
  46 };
  47
  48 /**
  49  * Used to mask off the mode types in the mode handler
  50  * array. Used in a simple two instruction hashing function
  51  * "(modeletter - 65) OR mask"
  52  */
  53 enum ModeMasks {
  54         MASK_USER = 128,        /* A user mode */
  55         MASK_CHANNEL = 0        /* A channel mode */
  56 };
  57
  58 /** Each mode is implemented by ONE ModeHandler class.
  59  * You must derive ModeHandler and add the child class to
  60  * the list of modes handled by the ircd, using
  61  * ModeParser::AddMode. When the mode you implement is
  62  * set by a user, the virtual function OnModeChange is
  63  * called. If you specify a value greater than 0 for
  64  * parameters_on or parameters_off, then when the mode is
  65  * set or unset respectively, std::string &parameter will
  66  * contain the parameter given by the user, else it will
  67  * contain an empty string. You may alter this parameter
  68  * string, and if you alter it to an empty string, and your
  69  * mode is expected to have a parameter, then this is
  70  * equivalent to returning MODEACTION_DENY.
  71  */
  72 class ModeHandler : public Extensible
  73 {
  74  protected:
  75         /**
  76          * The mode letter you're implementing.
  77          */
  78         char mode;
  79         /**
  80          * Number of parameters when being set
  81          */
  82         int n_params_on;
  83         /**
  84          * Number of parameters when being unset
  85          */
  86         int n_params_off;
  87         /**
  88          * Mode is a 'list' mode. The behaviour
  89          * of your mode is now set entirely within
  90          * the class as of the 1.1 api, rather than
  91          * inside the mode parser as in the 1.0 api,
  92          * so the only use of this value (along with
  93          * IsListMode()) is for the core to determine
  94          * wether your module can produce 'lists' or not
  95          * (e.g. banlists, etc)
  96          */
  97         bool list;
  98         /**
  99          * The mode type, either MODETYPE_USER or
 100          * MODETYPE_CHANNEL.
 101          */
 102         ModeType m_type;
 103         /**
 104          * True if the mode requires oper status
 105          * to set.
 106          */
 107         bool oper;
 108
 109  public:
 110         /**
 111          * The constructor for ModeHandler initalizes the mode handler.
 112          * The constructor of any class you derive from ModeHandler should
 113          * probably call this constructor with the parameters set correctly.
 114          * @param modeletter The mode letter you wish to handle
 115          * @param parameters_on The number of parameters your mode takes when being set. Note that any nonzero value is treated as 1.
 116          * @param parameters_off The number of parameters your mode takes when being unset. Note that any nonzero value is treated as 1.
 117          * @param listmode Set to true if your mode is a listmode, e.g. it will respond to MODE #channel +modechar with a list of items
 118          * @param ModeType Set this to MODETYPE_USER for a usermode, or MODETYPE_CHANNEL for a channelmode.
 119          * @param operonly Set this to true if only opers should be allowed to set or unset the mode.
 120          */
 121         ModeHandler(char modeletter, int parameters_on, int parameters_off, bool listmode, ModeType type, bool operonly);
 122         /**
 123          * The default destructor does nothing
 124          */
 125         virtual ~ModeHandler();
 126
 127         /**
 128          * Returns true if the mode is a list mode
 129          */
 130         bool IsListMode();
 131         /**
 132          * Returns the modes type
 133          */
 134         ModeType GetModeType();
 135         /**
 136          * Returns true if the mode can only be set/unset by an oper
 137          */
 138         bool NeedsOper();
 139         /**
 140          * Returns the number of parameters for the mode. Any non-zero
 141          * value should be considered to be equivalent to one.
 142          * @param adding If this is true, the number of parameters required to set the mode should be returned, otherwise the number of parameters required to unset the mode shall be returned.
 143          * @return The number of parameters the mode expects
 144          */
 145         int GetNumParams(bool adding);
 146         /**
 147          * Returns the mode character this handler handles.
 148          * @return The mode character
 149          */
 150         char GetModeChar();
 151
 152         /**
 153          * Called when a mode change for your mode occurs.
 154          * @param source Contains the user setting the mode.
 155          * @param dest For usermodes, contains the destination user the mode is being set on. For channelmodes, this is an undefined value.
 156          * @param channel For channel modes, contains the destination channel the modes are being set on. For usermodes, this is an undefined value.
 157          * @param parameter The parameter for your mode, if you indicated that your mode requires a parameter when being set or unset. Note that
 158          * if you alter this value, the new value becomes the one displayed and send out to the network, also, if you set this to an empty string
 159          * but you specified your mode REQUIRES a parameter, this is equivalent to returning MODEACTION_DENY and will prevent the mode from being
 160          * displayed.
 161          * @param adding This value is true when the mode is being set, or false when it is being unset.
 162          * @return MODEACTION_ALLOW to allow the mode, or MODEACTION_DENY to prevent the mode, also see the description of 'parameter'.
 163          */
 164         virtual ModeAction OnModeChange(userrec* source, userrec* dest, chanrec* channel, std::string &parameter, bool adding); /* Can change the mode parameter as its a ref */
 165         /**
 166          * If your mode is a listmode, then this method will be called for displaying an item list, e.g. on MODE #channel +modechar
 167          * without any parameter or other modes in the command.
 168          * @param user The user issuing the command
 169          * @parameter channel The channel they're requesting an item list of (e.g. a banlist, or an exception list etc)
 170          */
 171         virtual void DisplayList(userrec* user, chanrec* channel);
 172         /**
 173          * If your mode needs special action during a server sync to determine which side wins when comparing timestamps,
 174          * override this function and use it to return true or false. The default implementation just returns true if
 175          * theirs < ours.
 176          * @param theirs The timestamp of the remote side
 177          * @param ours The timestamp of the local side
 178          * @param their_param Their parameter if the mode has a parameter
 179          * @param our_param Our parameter if the mode has a parameter
 180          * @param channel The channel we are checking against
 181          * @return True if the other side wins the merge, false if we win the merge for this mode.
 182          */
 183         virtual bool CheckTimeStamp(time_t theirs, time_t ours, const std::string &their_param, const std::string &our_param, chanrec* channel);
 184
 185         virtual std::pair<bool,std::string> ModeSet(userrec* source, userrec* dest, chanrec* channel, const std::string &parameter);
 186 };
 187
 188 /**
 189  * The ModeWatcher class can be used to alter the behaviour of a mode implemented
 190  * by the core or by another module. To use ModeWatcher, derive a class from it,
 191  * and attach it to the mode using Server::AddModeWatcher and Server::DelModeWatcher.
 192  * A ModeWatcher will be called both before and after the mode change.
 193  */
 194 class ModeWatcher : public Extensible
 195 {
 196  protected:
 197         /**
 198          * The mode letter this class is watching
 199          */
 200         char mode;
 201         /**
 202          * The mode type being watched (user or  channel)
 203          */
 204         ModeType m_type;
 205
 206  public:
 207         /**
 208          * The constructor initializes the mode and the mode type
 209          */
 210         ModeWatcher(char modeletter, ModeType type);
 211         /**
 212          * The default destructor does nothing.
 213          */
 214         virtual ~ModeWatcher();
 215
 216         /**
 217          * Get the mode character being watched
 218          * @return The mode character being watched
 219          */
 220         char GetModeChar();
 221         /**
 222          * Get the mode type being watched
 223          * @return The mode type being watched (user or channel)
 224          */
 225         ModeType GetModeType();
 226
 227         /**
 228          * Before the mode character is processed by its handler, this method will be called.
 229          * @param source The sender of the mode
 230          * @param dest The target user for the mode, if you are watching a user mode
 231          * @param channel The target channel for the mode, if you are watching a channel mode
 232          * @param parameter The parameter of the mode, if the mode is supposed to have a parameter.
 233          * If you alter the parameter you are given, the mode handler will see your atered version
 234          * when it handles the mode.
 235          * @param adding True if the mode is being added and false if it is being removed
 236          * @type The mode type, either MODETYPE_USER or MODETYPE_CHANNEL
 237          * @return True to allow the mode change to go ahead, false to abort it. If you abort the
 238          * change, the mode handler (and ModeWatcher::AfterMode()) will never see the mode change.
 239          */
 240         virtual bool BeforeMode(userrec* source, userrec* dest, chanrec* channel, std::string &parameter, bool adding, ModeType type);
 241         /**
 242          * After the mode character has been processed by the ModeHandler, this method will be called.
 243          * @param source The sender of the mode
 244          * @param dest The target user for the mode, if you are watching a user mode
 245          * @param channel The target channel for the mode, if you are watching a channel mode
 246          * @param parameter The parameter of the mode, if the mode is supposed to have a parameter.
 247          * You cannot alter the parameter here, as the mode handler has already processed it.
 248          * @param adding True if the mode is being added and false if it is being removed
 249          * @type The mode type, either MODETYPE_USER or MODETYPE_CHANNEL
 250          */
 251         virtual void AfterMode(userrec* source, userrec* dest, chanrec* channel, const std::string &parameter, bool adding, ModeType type);
 252 };
 253
 254 typedef std::vector<ModeWatcher*>::iterator ModeWatchIter;
 255
 256 class ModeParser : public classbase
 257 {
 258  private:
 259         /**
 260          * Mode handlers for each mode, to access a handler subtract
 261          * 65 from the ascii value of the mode letter.
 262          * The upper bit of the value indicates if its a usermode
 263          * or a channel mode, so we have 256 of them not 64.
 264          */
 265         ModeHandler* modehandlers[256];
 266         /**
 267          * Mode watcher classes arranged in the same way as the
 268          * mode handlers, except for instead of having 256 of them
 269          * we have 256 lists of them.
 270          */
 271         std::vector<ModeWatcher*> modewatchers[256];
 272         /**
 273          * Displays the current modes of a channel or user.
 274          * Used by ModeParser::Process.
 275          */
 276         void DisplayCurrentModes(userrec *user, userrec* targetuser, chanrec* targetchannel, const char* text);
 277
 278  public:
 279
 280         /**
 281          * The constructor initializes all the RFC basic modes by using ModeParserAddMode().
 282          */
 283         ModeParser();
 284
 285         /**
 286          * Used to check if user 'd' should be allowed to do operation 'MASK' on channel 'chan'.
 287          * for example, should 'user A' be able to 'op' on 'channel B'.
 288          */
 289         static userrec* SanityChecks(userrec *user,const char *dest,chanrec *chan,int status);
 290         /**
 291          * Grant a built in privilage (e.g. ops, halfops, voice) to a user on a channel
 292          */
 293         static const char* Grant(userrec *d,chanrec *chan,int MASK);
 294         /**
 295          * Revoke a built in privilage (e.g. ops, halfops, voice) to a user on a channel
 296          */
 297         static const char* Revoke(userrec *d,chanrec *chan,int MASK);
 298         /**
 299          * Tidy a banmask. This makes a banmask 'acceptable' if fields are left out.
 300          * E.g.
 301          *
 302          * nick -> nick!*@*
 303          *
 304          * nick!ident -> nick!ident@*
 305          *
 306          * host.name -> *!*@host.name
 307          *
 308          * ident@host.name -> *!ident@host.name
 309          *
 310          * This method can be used on both IPV4 and IPV6 user masks.
 311          */
 312         static void CleanMask(std::string &mask);
 313         /**
 314          * Add a mode to the mode parser. The modeletter parameter
 315          * is purely to save on doing a lookup in the function, as
 316          * strictly it could be obtained via ModeHandler::GetModeChar().
 317          * @return True if the mode was successfully added.
 318          */
 319         bool AddMode(ModeHandler* mh, unsigned const char modeletter);
 320         /**
 321          * Add a mode watcher.
 322          * A mode watcher is triggered before and after a mode handler is
 323          * triggered. See the documentation of class ModeWatcher for more
 324          * information.
 325          * @param mw The ModeWatcher you want to add
 326          * @return True if the ModeWatcher was added correctly
 327          */
 328         bool AddModeWatcher(ModeWatcher* mw);
 329         /**
 330          * Delete a mode watcher.
 331          * A mode watcher is triggered before and after a mode handler is
 332          * triggered. See the documentation of class ModeWatcher for more
 333          * information.
 334          * @param mw The ModeWatcher you want to delete
 335          * @return True if the ModeWatcher was deleted correctly
 336          */
 337         bool DelModeWatcher(ModeWatcher* mw);
 338         /**
 339          * Process a set of mode changes from a server or user.
 340          * @param parameters The parameters of the mode change, in the format
 341          * they would be from a MODE command.
 342          * @param pcnt The number of items in the parameters array
 343          * @param user The user setting or removing the modes. When the modes are set
 344          * by a server, an 'uninitialized' userrec is used, where *user::nick == NULL
 345          * and *user->server == NULL.
 346          * @param servermode True if a server is setting the mode.
 347          */
 348         void Process(const char** parameters, int pcnt, userrec *user, bool servermode);
 349
 350         ModeHandler* FindMode(unsigned const char modeletter, ModeType mt);
 351 };
 352
 353 /**
 354  * Command handler class for the MODE command.
 355  * put here for completeness.
 356  */
 357 class cmd_mode : public command_t
 358 {
 359  public:
 360         /**
 361          * Standard constructor
 362          */
 363         cmd_mode () : command_t("MODE",0,1) { }
 364         /**
 365          * Handle MODE
 366          */
 367         void Handle(const char** parameters, int pcnt, userrec *user);
 368 };
 369
 370 #endif