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 class InspIRCd;
  32
  33 /**
  34  * Holds the values for different type of modes
  35  * that can exist, USER or CHANNEL type.
  36  */
  37 enum ModeType
  38 {
  39         MODETYPE_USER = 0,
  40         MODETYPE_CHANNEL = 1
  41 };
  42
  43 /**
  44  * Holds mode actions - modes can be allowed or denied.
  45  */
  46 enum ModeAction
  47 {
  48         MODEACTION_DENY = 0, /* Drop the mode change, AND a parameter if its a parameterized mode */
  49         MODEACTION_ALLOW = 1 /* Allow the mode */
  50 };
  51
  52 /**
  53  * Used to mask off the mode types in the mode handler
  54  * array. Used in a simple two instruction hashing function
  55  * "(modeletter - 65) OR mask"
  56  */
  57 enum ModeMasks
  58 {
  59         MASK_USER = 128,        /* A user mode */
  60         MASK_CHANNEL = 0        /* A channel mode */
  61 };
  62
  63 /**
  64  * These fixed values can be used to proportionally compare module-defined prefixes to known values.
  65  * For example, if your module queries a chanrec, and is told that user 'joebloggs' has the prefix
  66  * '$', and you dont know what $ means, then you can compare it to these three values to determine
  67  * its worth against them. For example if '$' had a value of 15000, you would know it is of higher
  68  * status than voice, but lower status than halfop.
  69  * No two modes should have equal prefix values.
  70  */
  71 enum PrefixModeValue
  72 {
  73         VOICE_VALUE     =       10000,
  74         HALFOP_VALUE    =       20000,
  75         OP_VALUE        =       30000
  76 };
  77
  78 /**
  79  * Used by ModeHandler::ModeSet() to return the state of a mode upon a channel or user.
  80  * The pair contains an activity flag, true if the mode is set with the given parameter,
  81  * and the parameter of the mode (or the parameter provided) in the std::string.
  82  */
  83 typedef std::pair<bool,std::string> ModePair;
  84
  85 /** Each mode is implemented by ONE ModeHandler class.
  86  * You must derive ModeHandler and add the child class to
  87  * the list of modes handled by the ircd, using
  88  * ModeParser::AddMode. When the mode you implement is
  89  * set by a user, the virtual function OnModeChange is
  90  * called. If you specify a value greater than 0 for
  91  * parameters_on or parameters_off, then when the mode is
  92  * set or unset respectively, std::string &parameter will
  93  * contain the parameter given by the user, else it will
  94  * contain an empty string. You may alter this parameter
  95  * string, and if you alter it to an empty string, and your
  96  * mode is expected to have a parameter, then this is
  97  * equivalent to returning MODEACTION_DENY.
  98  */
  99 class ModeHandler : public Extensible
 100 {
 101  protected:
 102         InspIRCd* ServerInstance;
 103         /**
 104          * The mode letter you're implementing.
 105          */
 106         char mode;
 107         /**
 108          * Number of parameters when being set
 109          */
 110         int n_params_on;
 111         /**
 112          * Number of parameters when being unset
 113          */
 114         int n_params_off;
 115         /**
 116          * Mode is a 'list' mode. The behaviour
 117          * of your mode is now set entirely within
 118          * the class as of the 1.1 api, rather than
 119          * inside the mode parser as in the 1.0 api,
 120          * so the only use of this value (along with
 121          * IsListMode()) is for the core to determine
 122          * wether your module can produce 'lists' or not
 123          * (e.g. banlists, etc)
 124          */
 125         bool list;
 126         /**
 127          * The mode type, either MODETYPE_USER or
 128          * MODETYPE_CHANNEL.
 129          */
 130         ModeType m_type;
 131         /**
 132          * True if the mode requires oper status
 133          * to set.
 134          */
 135         bool oper;
 136
 137         /** Mode prefix, or 0
 138          */
 139         char prefix;
 140
 141  public:
 142         /**
 143          * The constructor for ModeHandler initalizes the mode handler.
 144          * The constructor of any class you derive from ModeHandler should
 145          * probably call this constructor with the parameters set correctly.
 146          * @param modeletter The mode letter you wish to handle
 147          * @param parameters_on The number of parameters your mode takes when being set. Note that any nonzero value is treated as 1.
 148          * @param parameters_off The number of parameters your mode takes when being unset. Note that any nonzero value is treated as 1.
 149          * @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
 150          * @param ModeType Set this to MODETYPE_USER for a usermode, or MODETYPE_CHANNEL for a channelmode.
 151          * @param operonly Set this to true if only opers should be allowed to set or unset the mode.
 152          * @param mprefix For listmodes where parameters are NICKNAMES which are on the channel (for example, +ohv), you may define a prefix.
 153          * When you define a prefix, it can be returned in NAMES, WHO etc if it has the highest value (as returned by GetPrefixRank())
 154          * In the core, the only modes to implement prefixes are +ovh (ops, voice, halfop) which define the prefix characters @, % and +
 155          * and the rank values OP_VALUE, HALFOP_VALUE and VOICE_VALUE respectively. Any prefixes you define should have unique values proportional
 156          * to these three defaults or proportional to another mode in a module you depend on. See src/cmode_o.cpp as an example.
 157          */
 158         ModeHandler(InspIRCd* Instance, char modeletter, int parameters_on, int parameters_off, bool listmode, ModeType type, bool operonly, char mprefix = 0);
 159         /**
 160          * The default destructor does nothing
 161          */
 162         virtual ~ModeHandler();
 163         /**
 164          * Returns true if the mode is a list mode
 165          */
 166         bool IsListMode();
 167         /**
 168          * Mode prefix or 0. If this is defined, you should
 169          * also implement GetPrefixRank() to return an integer
 170          * value for this mode prefix.
 171          */
 172         char GetPrefix();
 173         /**
 174          * Get the 'value' of this modes prefix.
 175          * determines which to display when there are multiple.
 176          * The mode with the highest value is ranked first. See the
 177          * PrefixModeValue enum and chanrec::GetPrefixValue() for
 178          * more information.
 179          */
 180         virtual unsigned int GetPrefixRank();
 181         /**
 182          * Returns the modes type
 183          */
 184         ModeType GetModeType();
 185         /**
 186          * Returns true if the mode can only be set/unset by an oper
 187          */
 188         bool NeedsOper();
 189         /**
 190          * Returns the number of parameters for the mode. Any non-zero
 191          * value should be considered to be equivalent to one.
 192          * @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.
 193          * @return The number of parameters the mode expects
 194          */
 195         int GetNumParams(bool adding);
 196         /**
 197          * Returns the mode character this handler handles.
 198          * @return The mode character
 199          */
 200         char GetModeChar();
 201
 202         /**
 203          * Called when a mode change for your mode occurs.
 204          * @param source Contains the user setting the mode.
 205          * @param dest For usermodes, contains the destination user the mode is being set on. For channelmodes, this is an undefined value.
 206          * @param channel For channel modes, contains the destination channel the modes are being set on. For usermodes, this is an undefined value.
 207          * @param parameter The parameter for your mode, if you indicated that your mode requires a parameter when being set or unset. Note that
 208          * 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
 209          * but you specified your mode REQUIRES a parameter, this is equivalent to returning MODEACTION_DENY and will prevent the mode from being
 210          * displayed.
 211          * @param adding This value is true when the mode is being set, or false when it is being unset.
 212          * @return MODEACTION_ALLOW to allow the mode, or MODEACTION_DENY to prevent the mode, also see the description of 'parameter'.
 213          */
 214         virtual ModeAction OnModeChange(userrec* source, userrec* dest, chanrec* channel, std::string &parameter, bool adding); /* Can change the mode parameter as its a ref */
 215         /**
 216          * If your mode is a listmode, then this method will be called for displaying an item list, e.g. on MODE #channel +modechar
 217          * without any parameter or other modes in the command.
 218          * @param user The user issuing the command
 219          * @parameter channel The channel they're requesting an item list of (e.g. a banlist, or an exception list etc)
 220          */
 221         virtual void DisplayList(userrec* user, chanrec* channel);
 222         /**
 223          * If your mode needs special action during a server sync to determine which side wins when comparing timestamps,
 224          * override this function and use it to return true or false. The default implementation just returns true if
 225          * theirs < ours. This will only be called for non-listmodes with parameters, when adding the mode and where
 226          * theirs == ours (therefore the default implementation will always return false).
 227          * @param theirs The timestamp of the remote side
 228          * @param ours The timestamp of the local side
 229          * @param their_param Their parameter if the mode has a parameter
 230          * @param our_param Our parameter if the mode has a parameter
 231          * @param channel The channel we are checking against
 232          * @return True if the other side wins the merge, false if we win the merge for this mode.
 233          */
 234         virtual bool CheckTimeStamp(time_t theirs, time_t ours, const std::string &their_param, const std::string &our_param, chanrec* channel);
 235
 236         /**
 237          * When a remote server needs to bounce a set of modes, it will call this method for every mode
 238          * in the mode string to determine if the mode is set or not.
 239          * @param source of the mode change, this will be NULL for a server mode
 240          * @param dest Target user of the mode change, if this is a user mode
 241          * @param channel Target channel of the mode change, if this is a channel mode
 242          * @param parameter The parameter given for the mode change, or an empty string
 243          * @returns The first value of the pair should be true if the mode is set with the given parameter.
 244          * In the case of permissions modes such as channelmode +o, this should return true if the user given
 245          * as the parameter has the given privilage on the given channel. The string value of the pair will hold
 246          * the current setting for this mode set locally, when the bool is true, or, the parameter given.
 247          * This allows the local server to enforce our locally set parameters back to a remote server.
 248          */
 249         virtual ModePair ModeSet(userrec* source, userrec* dest, chanrec* channel, const std::string &parameter);
 250 };
 251
 252 /**
 253  * The ModeWatcher class can be used to alter the behaviour of a mode implemented
 254  * by the core or by another module. To use ModeWatcher, derive a class from it,
 255  * and attach it to the mode using Server::AddModeWatcher and Server::DelModeWatcher.
 256  * A ModeWatcher will be called both before and after the mode change.
 257  */
 258 class ModeWatcher : public Extensible
 259 {
 260  protected:
 261         InspIRCd* ServerInstance;
 262         /**
 263          * The mode letter this class is watching
 264          */
 265         char mode;
 266         /**
 267          * The mode type being watched (user or  channel)
 268          */
 269         ModeType m_type;
 270
 271  public:
 272         /**
 273          * The constructor initializes the mode and the mode type
 274          */
 275         ModeWatcher(InspIRCd* Instance, char modeletter, ModeType type);
 276         /**
 277          * The default destructor does nothing.
 278          */
 279         virtual ~ModeWatcher();
 280
 281         /**
 282          * Get the mode character being watched
 283          * @return The mode character being watched
 284          */
 285         char GetModeChar();
 286         /**
 287          * Get the mode type being watched
 288          * @return The mode type being watched (user or channel)
 289          */
 290         ModeType GetModeType();
 291
 292         /**
 293          * Before the mode character is processed by its handler, this method will be called.
 294          * @param source The sender of the mode
 295          * @param dest The target user for the mode, if you are watching a user mode
 296          * @param channel The target channel for the mode, if you are watching a channel mode
 297          * @param parameter The parameter of the mode, if the mode is supposed to have a parameter.
 298          * If you alter the parameter you are given, the mode handler will see your atered version
 299          * when it handles the mode.
 300          * @param adding True if the mode is being added and false if it is being removed
 301          * @type The mode type, either MODETYPE_USER or MODETYPE_CHANNEL
 302          * @return True to allow the mode change to go ahead, false to abort it. If you abort the
 303          * change, the mode handler (and ModeWatcher::AfterMode()) will never see the mode change.
 304          */
 305         virtual bool BeforeMode(userrec* source, userrec* dest, chanrec* channel, std::string &parameter, bool adding, ModeType type);
 306         /**
 307          * After the mode character has been processed by the ModeHandler, this method will be called.
 308          * @param source The sender of the mode
 309          * @param dest The target user for the mode, if you are watching a user mode
 310          * @param channel The target channel for the mode, if you are watching a channel mode
 311          * @param parameter The parameter of the mode, if the mode is supposed to have a parameter.
 312          * You cannot alter the parameter here, as the mode handler has already processed it.
 313          * @param adding True if the mode is being added and false if it is being removed
 314          * @type The mode type, either MODETYPE_USER or MODETYPE_CHANNEL
 315          */
 316         virtual void AfterMode(userrec* source, userrec* dest, chanrec* channel, const std::string &parameter, bool adding, ModeType type);
 317 };
 318
 319 typedef std::vector<ModeWatcher*>::iterator ModeWatchIter;
 320
 321 /** The mode parser handles routing of modes and handling of mode strings.
 322  * It marshalls, controls and maintains both ModeWatcher and ModeHandler classes,
 323  * parses client to server MODE strings for user and channel modes, and performs
 324  * processing for the 004 mode list numeric, amongst other things.
 325  */
 326 class ModeParser : public classbase
 327 {
 328  private:
 329         InspIRCd* ServerInstance;
 330         /** Mode handlers for each mode, to access a handler subtract
 331          * 65 from the ascii value of the mode letter.
 332          * The upper bit of the value indicates if its a usermode
 333          * or a channel mode, so we have 256 of them not 64.
 334          */
 335         ModeHandler* modehandlers[256];
 336         /** Mode watcher classes arranged in the same way as the
 337          * mode handlers, except for instead of having 256 of them
 338          * we have 256 lists of them.
 339          */
 340         std::vector<ModeWatcher*> modewatchers[256];
 341         /** Displays the current modes of a channel or user.
 342          * Used by ModeParser::Process.
 343          */
 344         void DisplayCurrentModes(userrec *user, userrec* targetuser, chanrec* targetchannel, const char* text);
 345
 346  public:
 347
 348         /** The constructor initializes all the RFC basic modes by using ModeParserAddMode().
 349          */
 350         ModeParser(InspIRCd* Instance);
 351
 352         /** Used to check if user 'd' should be allowed to do operation 'MASK' on channel 'chan'.
 353          * for example, should 'user A' be able to 'op' on 'channel B'.
 354          */
 355         userrec* SanityChecks(userrec *user,const char *dest,chanrec *chan,int status);
 356         /** Grant a built in privilage (e.g. ops, halfops, voice) to a user on a channel
 357          */
 358         const char* Grant(userrec *d,chanrec *chan,int MASK);
 359         /** Revoke a built in privilage (e.g. ops, halfops, voice) to a user on a channel
 360          */
 361         const char* Revoke(userrec *d,chanrec *chan,int MASK);
 362         /** Tidy a banmask. This makes a banmask 'acceptable' if fields are left out.
 363          * E.g.
 364          *
 365          * nick -> nick!*@*
 366          *
 367          * nick!ident -> nick!ident@*
 368          *
 369          * host.name -> *!*@host.name
 370          *
 371          * ident@host.name -> *!ident@host.name
 372          *
 373          * This method can be used on both IPV4 and IPV6 user masks.
 374          */
 375         static void CleanMask(std::string &mask);
 376         /** Add a mode to the mode parser. The modeletter parameter
 377          * is purely to save on doing a lookup in the function, as
 378          * strictly it could be obtained via ModeHandler::GetModeChar().
 379          * @return True if the mode was successfully added.
 380          */
 381         bool AddMode(ModeHandler* mh, unsigned const char modeletter);
 382         /** Add a mode watcher.
 383          * A mode watcher is triggered before and after a mode handler is
 384          * triggered. See the documentation of class ModeWatcher for more
 385          * information.
 386          * @param mw The ModeWatcher you want to add
 387          * @return True if the ModeWatcher was added correctly
 388          */
 389         bool AddModeWatcher(ModeWatcher* mw);
 390         /** Delete a mode watcher.
 391          * A mode watcher is triggered before and after a mode handler is
 392          * triggered. See the documentation of class ModeWatcher for more
 393          * information.
 394          * @param mw The ModeWatcher you want to delete
 395          * @return True if the ModeWatcher was deleted correctly
 396          */
 397         bool DelModeWatcher(ModeWatcher* mw);
 398         /** Process a set of mode changes from a server or user.
 399          * @param parameters The parameters of the mode change, in the format
 400          * they would be from a MODE command.
 401          * @param pcnt The number of items in the parameters array
 402          * @param user The user setting or removing the modes. When the modes are set
 403          * by a server, an 'uninitialized' userrec is used, where *user::nick == NULL
 404          * and *user->server == NULL.
 405          * @param servermode True if a server is setting the mode.
 406          */
 407         void Process(const char** parameters, int pcnt, userrec *user, bool servermode);
 408
 409         /** Find the mode handler for a given mode and type.
 410          * @param modeletter mode letter to search for
 411          * @param type of mode to search for, user or channel
 412          * @returns a pointer to a ModeHandler class, or NULL of there isnt a handler for the given mode
 413          */
 414         ModeHandler* FindMode(unsigned const char modeletter, ModeType mt);
 415
 416         /** Find a mode handler by its prefix.
 417          * If there is no mode handler with the given prefix, NULL will be returned.
 418          * @param pfxletter The prefix to find, e.g. '@'
 419          * @return The mode handler which handles this prefix, or NULL if there is none.
 420          */
 421         ModeHandler* FindPrefix(unsigned const char pfxletter);
 422
 423         /** Returns a list of mode characters which are usermodes.
 424          * This is used in the 004 numeric when users connect.
 425          */
 426         std::string UserModeList();
 427
 428         /** Returns a list of channel mode characters which are listmodes.
 429          * This is used in the 004 numeric when users connect.
 430          */
 431         std::string ChannelModeList();
 432
 433         /** Returns a list of channel mode characters which take parameters.
 434          * This is used in the 004 numeric when users connect.
 435          */
 436         std::string ParaModeList();
 437
 438         /** Generates the CHANMODES= 005 sequence
 439          */
 440         std::string ChanModes();
 441         /** Used by this class internally during std::sort and 005 generation
 442          */
 443         static bool ModeParser::PrefixComparison(const prefixtype one, const prefixtype two);
 444
 445         /** This returns the PREFIX=(ohv)@%+ section of the 005 numeric.
 446          */
 447         std::string BuildPrefixes();
 448
 449         /** This returns the privilages of a user upon a channel, in the format of a mode change.
 450          * For example, if a user has privilages +avh, this will return the string "avh nick nick nick".
 451          * This is used by the core when cycling a user to refresh their hostname. You may use it for
 452          * similar purposes.
 453          * @param user The username to look up
 454          * @param channel The channel name to look up the privilages of the user for
 455          * @return The mode string.
 456          */
 457         std::string ModeString(userrec* user, chanrec* channel);
 458 };
 459
 460 /** Command handler class for the MODE command.
 461  * put here for completeness.
 462  */
 463 class cmd_mode : public command_t
 464 {
 465  public:
 466         /** Standard constructor
 467          */
 468         cmd_mode (InspIRCd* Instance) : command_t(Instance,"MODE",0,1) { syntax = "<target> <modes> {<mode-parameters>}"; }
 469         /** Handle MODE
 470          */
 471         void Handle(const char** parameters, int pcnt, userrec *user);
 472 };
 473
 474 #endif