include/mode.h

   1 /*
   2  * InspIRCd -- Internet Relay Chat Daemon
   3  *
   4  *   Copyright (C) 2009 Daniel De Graaf <danieldg@inspircd.org>
   5  *   Copyright (C) 2004-2006, 2008 Craig Edwards <craigedwards@brainbox.cc>
   6  *   Copyright (C) 2007 Robin Burchell <robin+git@viroteck.net>
   7  *   Copyright (C) 2007 Dennis Friis <peavey@inspircd.org>
   8  *
   9  * This file is part of InspIRCd.  InspIRCd is free software: you can
  10  * redistribute it and/or modify it under the terms of the GNU General Public
  11  * License as published by the Free Software Foundation, version 2.
  12  *
  13  * This program is distributed in the hope that it will be useful, but WITHOUT
  14  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  15  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  16  * details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  20  */
  21
  22
  23 #ifndef MODE_H
  24 #define MODE_H
  25
  26 #include "ctables.h"
  27
  28 /**
  29  * Holds the values for different type of modes
  30  * that can exist, USER or CHANNEL type.
  31  */
  32 enum ModeType
  33 {
  34         /** User mode */
  35         MODETYPE_USER = 0,
  36         /** Channel mode */
  37         MODETYPE_CHANNEL = 1
  38 };
  39
  40 /**
  41  * Holds mode actions - modes can be allowed or denied.
  42  */
  43 enum ModeAction
  44 {
  45         MODEACTION_DENY = 0, /* Drop the mode change, AND a parameter if its a parameterized mode */
  46         MODEACTION_ALLOW = 1 /* Allow the mode */
  47 };
  48
  49 /**
  50  * Used to mask off the mode types in the mode handler
  51  * array. Used in a simple two instruction hashing function
  52  * "(modeletter - 65) OR mask"
  53  */
  54 enum ModeMasks
  55 {
  56         MASK_USER = 128,        /* A user mode */
  57         MASK_CHANNEL = 0        /* A channel mode */
  58 };
  59
  60 /**
  61  * These fixed values can be used to proportionally compare module-defined prefixes to known values.
  62  * For example, if your module queries a Channel, and is told that user 'joebloggs' has the prefix
  63  * '$', and you dont know what $ means, then you can compare it to these three values to determine
  64  * its worth against them. For example if '$' had a value of 15000, you would know it is of higher
  65  * status than voice, but lower status than halfop.
  66  * No two modes should have equal prefix values.
  67  */
  68 enum PrefixModeValue
  69 {
  70         /* +v */
  71         VOICE_VALUE     =       10000,
  72         /* +h */
  73         HALFOP_VALUE    =       20000,
  74         /* +o */
  75         OP_VALUE        =       30000
  76 };
  77
  78 enum ParamSpec
  79 {
  80         /** No parameters */
  81         PARAM_NONE,
  82         /** Parameter required on mode setting only */
  83         PARAM_SETONLY,
  84         /** Parameter always required */
  85         PARAM_ALWAYS
  86 };
  87
  88 /** Each mode is implemented by ONE ModeHandler class.
  89  * You must derive ModeHandler and add the child class to
  90  * the list of modes handled by the ircd, using
  91  * ModeParser::AddMode. When the mode you implement is
  92  * set by a user, the virtual function OnModeChange is
  93  * called. If you specify a value greater than 0 for
  94  * parameters_on or parameters_off, then when the mode is
  95  * set or unset respectively, std::string &parameter will
  96  * contain the parameter given by the user, else it will
  97  * contain an empty string. You may alter this parameter
  98  * string, and if you alter it to an empty string, and your
  99  * mode is expected to have a parameter, then this is
 100  * equivalent to returning MODEACTION_DENY.
 101  */
 102 class CoreExport ModeHandler : public ServiceProvider
 103 {
 104  protected:
 105         /**
 106          * The mode parameter translation type
 107          */
 108         TranslateType m_paramtype;
 109
 110         /** What kind of parameters does the mode take?
 111          */
 112         ParamSpec parameters_taken;
 113
 114         /**
 115          * The mode letter you're implementing.
 116          */
 117         char mode;
 118
 119         /** Mode prefix, or 0
 120          */
 121         char prefix;
 122
 123         /**
 124          * True if the mode requires oper status
 125          * to set.
 126          */
 127         bool oper;
 128
 129         /**
 130          * Mode is a 'list' mode. The behaviour
 131          * of your mode is now set entirely within
 132          * the class as of the 1.1 api, rather than
 133          * inside the mode parser as in the 1.0 api,
 134          * so the only use of this value (along with
 135          * IsListMode()) is for the core to determine
 136          * wether your module can produce 'lists' or not
 137          * (e.g. banlists, etc)
 138          */
 139         bool list;
 140
 141         /**
 142          * The mode type, either MODETYPE_USER or
 143          * MODETYPE_CHANNEL.
 144          */
 145         ModeType m_type;
 146
 147         /** The prefix char needed on channel to use this mode,
 148          * only checked for channel modes
 149          */
 150         int levelrequired;
 151
 152  public:
 153         /**
 154          * The constructor for ModeHandler initalizes the mode handler.
 155          * The constructor of any class you derive from ModeHandler should
 156          * probably call this constructor with the parameters set correctly.
 157          * @param me The module which created this mode
 158          * @param name A one-word name for the mode
 159          * @param modeletter The mode letter you wish to handle
 160          * @param params Parameters taken by the mode
 161          * @param type Type of the mode (MODETYPE_USER or MODETYPE_CHANNEL)
 162          */
 163         ModeHandler(Module* me, const std::string& name, char modeletter, ParamSpec params, ModeType type);
 164         virtual CullResult cull();
 165         virtual ~ModeHandler();
 166         /**
 167          * Returns true if the mode is a list mode
 168          */
 169         bool IsListMode();
 170         /**
 171          * Mode prefix or 0. If this is defined, you should
 172          * also implement GetPrefixRank() to return an integer
 173          * value for this mode prefix.
 174          */
 175         inline char GetPrefix() const { return prefix; }
 176         /**
 177          * Get the 'value' of this modes prefix.
 178          * determines which to display when there are multiple.
 179          * The mode with the highest value is ranked first. See the
 180          * PrefixModeValue enum and Channel::GetPrefixValue() for
 181          * more information.
 182          */
 183         virtual unsigned int GetPrefixRank();
 184         /**
 185          * Returns the mode's type
 186          */
 187         inline ModeType GetModeType() const { return m_type; }
 188         /**
 189          * Returns the mode's parameter translation type
 190          */
 191         inline TranslateType GetTranslateType() const { return m_paramtype; }
 192         /**
 193          * Returns true if the mode can only be set/unset by an oper
 194          */
 195         inline bool NeedsOper() const { return oper; }
 196         /**
 197          * Returns the number of parameters for the mode. Any non-zero
 198          * value should be considered to be equivalent to one.
 199          * @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.
 200          * @return The number of parameters the mode expects
 201          */
 202         int GetNumParams(bool adding);
 203         /**
 204          * Returns the mode character this handler handles.
 205          * @return The mode character
 206          */
 207         inline char GetModeChar() { return mode; }
 208
 209         /** For user modes, return the current parameter, if any
 210          */
 211         virtual std::string GetUserParameter(User* useor);
 212
 213         /**
 214          * Called when a channel mode change access check for your mode occurs.
 215          * @param source Contains the user setting the mode.
 216          * @param channel contains the destination channel the modes are being set on.
 217          * @param parameter The parameter for your mode. This is modifiable.
 218          * @param adding This value is true when the mode is being set, or false when it is being unset.
 219          * @return allow, deny, or passthru to check against the required level
 220          */
 221         virtual ModResult AccessCheck(User* source, Channel* channel, std::string &parameter, bool adding);
 222
 223         /**
 224          * Called when a mode change for your mode occurs.
 225          * @param source Contains the user setting the mode.
 226          * @param dest For usermodes, contains the destination user the mode is being set on. For channelmodes, this is an undefined value.
 227          * @param channel For channel modes, contains the destination channel the modes are being set on. For usermodes, this is an undefined value.
 228          * @param parameter The parameter for your mode, if you indicated that your mode requires a parameter when being set or unset. Note that
 229          * 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
 230          * but you specified your mode REQUIRES a parameter, this is equivalent to returning MODEACTION_DENY and will prevent the mode from being
 231          * displayed.
 232          * @param adding This value is true when the mode is being set, or false when it is being unset.
 233          * @return MODEACTION_ALLOW to allow the mode, or MODEACTION_DENY to prevent the mode, also see the description of 'parameter'.
 234          */
 235         virtual ModeAction OnModeChange(User* source, User* dest, Channel* channel, std::string &parameter, bool adding); /* Can change the mode parameter as its a ref */
 236         /**
 237          * If your mode is a listmode, then this method will be called for displaying an item list, e.g. on MODE \#channel +modechar
 238          * without any parameter or other modes in the command.
 239          * @param user The user issuing the command
 240          * @param channel The channel they're requesting an item list of (e.g. a banlist, or an exception list etc)
 241          */
 242         virtual void DisplayList(User* user, Channel* channel);
 243
 244         /** In the event that the mode should be given a parameter, and no parameter was provided, this method is called.
 245          * This allows you to give special information to the user, or handle this any way you like.
 246          * @param user The user issuing the mode change
 247          * @param dest For user mode changes, the target of the mode. For channel mode changes, NULL.
 248          * @param channel For channel mode changes, the target of the mode. For user mode changes, NULL.
 249          */
 250         virtual void OnParameterMissing(User* user, User* dest, Channel* channel);
 251
 252         /**
 253          * If your mode is a listmode, this method will be called to display an empty list (just the end of list numeric)
 254          * @param user The user issuing the command
 255          * @param channel The channel tehy're requesting an item list of (e.g. a banlist, or an exception list etc)
 256          */
 257         virtual void DisplayEmptyList(User* user, Channel* channel);
 258
 259         /**
 260          * If your mode needs special action during a server sync to determine which side wins when comparing timestamps,
 261          * override this function and use it to return true or false. The default implementation just returns true if
 262          * theirs < ours. This will only be called for non-listmodes with parameters, when adding the mode and where
 263          * theirs == ours (therefore the default implementation will always return false).
 264          * @param their_param Their parameter if the mode has a parameter
 265          * @param our_param Our parameter if the mode has a parameter
 266          * @param channel The channel we are checking against
 267          * @return True if the other side wins the merge, false if we win the merge for this mode.
 268          */
 269         virtual bool ResolveModeConflict(std::string &their_param, const std::string &our_param, Channel* channel);
 270
 271         /**
 272          * When a MODETYPE_USER mode handler is being removed, the server will call this method for every user on the server.
 273          * Your mode handler should remove its user mode from the user by sending the appropriate server modes using
 274          * InspIRCd::SendMode(). The default implementation of this method can remove simple modes which have no parameters,
 275          * and can be used when your mode is of this type, otherwise you must implement a more advanced version of it to remove
 276          * your mode properly from each user.
 277          * @param user The user which the server wants to remove your mode from
 278          * @param stack The mode stack to add the mode change to
 279          */
 280         virtual void RemoveMode(User* user, irc::modestacker* stack = NULL);
 281
 282         /**
 283          * When a MODETYPE_CHANNEL mode handler is being removed, the server will call this method for every channel on the server.
 284          * Your mode handler should remove its user mode from the channel by sending the appropriate server modes using
 285          * InspIRCd::SendMode(). The default implementation of this method can remove simple modes which have no parameters,
 286          * and can be used when your mode is of this type, otherwise you must implement a more advanced version of it to remove
 287          * your mode properly from each channel. Note that in the case of listmodes, you should remove the entire list of items.
 288          * @param channel The channel which the server wants to remove your mode from
 289          * @param stack The mode stack to add the mode change to
 290          */
 291         virtual void RemoveMode(Channel* channel, irc::modestacker* stack = NULL);
 292
 293         inline unsigned int GetLevelRequired() const { return levelrequired; }
 294 };
 295
 296 /** A prebuilt mode handler which handles a simple user mode, e.g. no parameters, usable by any user, with no extra
 297  * behaviour to the mode beyond the basic setting and unsetting of the mode, not allowing the mode to be set if it
 298  * is already set and not allowing it to be unset if it is already unset.
 299  * An example of a simple user mode is user mode +w.
 300  */
 301 class CoreExport SimpleUserModeHandler : public ModeHandler
 302 {
 303  public:
 304         SimpleUserModeHandler(Module* Creator, const std::string& Name, char modeletter)
 305                 : ModeHandler(Creator, Name, modeletter, PARAM_NONE, MODETYPE_USER) {}
 306         virtual ~SimpleUserModeHandler() {}
 307         virtual ModeAction OnModeChange(User* source, User* dest, Channel* channel, std::string &parameter, bool adding);
 308 };
 309
 310 /** A prebuilt mode handler which handles a simple channel mode, e.g. no parameters, usable by any user, with no extra
 311  * behaviour to the mode beyond the basic setting and unsetting of the mode, not allowing the mode to be set if it
 312  * is already set and not allowing it to be unset if it is already unset.
 313  * An example of a simple channel mode is channel mode +s.
 314  */
 315 class CoreExport SimpleChannelModeHandler : public ModeHandler
 316 {
 317  public:
 318         SimpleChannelModeHandler(Module* Creator, const std::string& Name, char modeletter)
 319                 : ModeHandler(Creator, Name, modeletter, PARAM_NONE, MODETYPE_CHANNEL) {}
 320         virtual ~SimpleChannelModeHandler() {}
 321         virtual ModeAction OnModeChange(User* source, User* dest, Channel* channel, std::string &parameter, bool adding);
 322 };
 323
 324 class CoreExport ParamChannelModeHandler : public ModeHandler
 325 {
 326  public:
 327         ParamChannelModeHandler(Module* Creator, const std::string& Name, char modeletter)
 328                 : ModeHandler(Creator, Name, modeletter, PARAM_SETONLY, MODETYPE_CHANNEL) {}
 329         virtual ModeAction OnModeChange(User* source, User* dest, Channel* channel, std::string &parameter, bool adding);
 330         /** Validate the parameter - you may change the value to normalize it. Return true if it is valid. */
 331         virtual bool ParamValidate(std::string& parameter);
 332 };
 333
 334 /**
 335  * The ModeWatcher class can be used to alter the behaviour of a mode implemented
 336  * by the core or by another module. To use ModeWatcher, derive a class from it,
 337  * and attach it to the mode using Server::AddModeWatcher and Server::DelModeWatcher.
 338  * A ModeWatcher will be called both before and after the mode change.
 339  */
 340 class CoreExport ModeWatcher : public classbase
 341 {
 342  protected:
 343         /**
 344          * The mode letter this class is watching
 345          */
 346         char mode;
 347         /**
 348          * The mode type being watched (user or channel)
 349          */
 350         ModeType m_type;
 351
 352  public:
 353         ModuleRef creator;
 354         /**
 355          * The constructor initializes the mode and the mode type
 356          */
 357         ModeWatcher(Module* creator, char modeletter, ModeType type);
 358         /**
 359          * The default destructor does nothing.
 360          */
 361         virtual ~ModeWatcher();
 362
 363         /**
 364          * Get the mode character being watched
 365          * @return The mode character being watched
 366          */
 367         char GetModeChar();
 368         /**
 369          * Get the mode type being watched
 370          * @return The mode type being watched (user or channel)
 371          */
 372         ModeType GetModeType();
 373
 374         /**
 375          * Before the mode character is processed by its handler, this method will be called.
 376          * @param source The sender of the mode
 377          * @param dest The target user for the mode, if you are watching a user mode
 378          * @param channel The target channel for the mode, if you are watching a channel mode
 379          * @param parameter The parameter of the mode, if the mode is supposed to have a parameter.
 380          * If you alter the parameter you are given, the mode handler will see your atered version
 381          * when it handles the mode.
 382          * @param adding True if the mode is being added and false if it is being removed
 383          * @param type The mode type, either MODETYPE_USER or MODETYPE_CHANNEL
 384          * @return True to allow the mode change to go ahead, false to abort it. If you abort the
 385          * change, the mode handler (and ModeWatcher::AfterMode()) will never see the mode change.
 386          */
 387         virtual bool BeforeMode(User* source, User* dest, Channel* channel, std::string &parameter, bool adding, ModeType type);
 388         /**
 389          * After the mode character has been processed by the ModeHandler, this method will be called.
 390          * @param source The sender of the mode
 391          * @param dest The target user for the mode, if you are watching a user mode
 392          * @param channel The target channel for the mode, if you are watching a channel mode
 393          * @param parameter The parameter of the mode, if the mode is supposed to have a parameter.
 394          * You cannot alter the parameter here, as the mode handler has already processed it.
 395          * @param adding True if the mode is being added and false if it is being removed
 396          * @param type The mode type, either MODETYPE_USER or MODETYPE_CHANNEL
 397          */
 398         virtual void AfterMode(User* source, User* dest, Channel* channel, const std::string &parameter, bool adding, ModeType type);
 399 };
 400
 401 typedef std::vector<ModeWatcher*>::iterator ModeWatchIter;
 402
 403 /** The mode parser handles routing of modes and handling of mode strings.
 404  * It marshalls, controls and maintains both ModeWatcher and ModeHandler classes,
 405  * parses client to server MODE strings for user and channel modes, and performs
 406  * processing for the 004 mode list numeric, amongst other things.
 407  */
 408 class CoreExport ModeParser
 409 {
 410  private:
 411         /** Mode handlers for each mode, to access a handler subtract
 412          * 65 from the ascii value of the mode letter.
 413          * The upper bit of the value indicates if its a usermode
 414          * or a channel mode, so we have 256 of them not 64.
 415          */
 416         ModeHandler* modehandlers[256];
 417         /** Mode watcher classes arranged in the same way as the
 418          * mode handlers, except for instead of having 256 of them
 419          * we have 256 lists of them.
 420          */
 421         std::vector<ModeWatcher*> modewatchers[256];
 422         /** Displays the current modes of a channel or user.
 423          * Used by ModeParser::Process.
 424          */
 425         void DisplayCurrentModes(User *user, User* targetuser, Channel* targetchannel, const char* text);
 426         /** Displays the value of a list mode
 427          * Used by ModeParser::Process.
 428          */
 429         void DisplayListModes(User* user, Channel* chan, std::string &mode_sequence);
 430
 431         /**
 432          * Attempts to apply a mode change to a user or channel
 433          */
 434         ModeAction TryMode(User* user, User* targu, Channel* targc, bool adding, unsigned char mode, std::string &param, bool SkipACL);
 435
 436         /** The string representing the last set of modes to be parsed.
 437          * Use GetLastParse() to get this value, to be used for  display purposes.
 438          */
 439         std::string LastParse;
 440         std::vector<std::string> LastParseParams;
 441         std::vector<TranslateType> LastParseTranslate;
 442
 443         unsigned int sent[256];
 444
 445         unsigned int seq;
 446
 447  public:
 448
 449         /** The constructor initializes all the RFC basic modes by using ModeParserAddMode().
 450          */
 451         ModeParser();
 452         ~ModeParser();
 453
 454         /** Used to check if user 'd' should be allowed to do operation 'MASK' on channel 'chan'.
 455          * for example, should 'user A' be able to 'op' on 'channel B'.
 456          */
 457         User* SanityChecks(User *user,const char *dest,Channel *chan,int status);
 458         /** Tidy a banmask. This makes a banmask 'acceptable' if fields are left out.
 459          * E.g.
 460          *
 461          * nick -> nick!*@*
 462          *
 463          * nick!ident -> nick!ident@*
 464          *
 465          * host.name -> *!*\@host.name
 466          *
 467          * ident@host.name -> *!ident\@host.name
 468          *
 469          * This method can be used on both IPV4 and IPV6 user masks.
 470          */
 471         static void CleanMask(std::string &mask);
 472         /** Get the last string to be processed, as it was sent to the user or channel.
 473          * Use this to display a string you just sent to be parsed, as the actual output
 474          * may be different to what you sent after it has been 'cleaned up' by the parser.
 475          * @return Last parsed string, as seen by users.
 476          */
 477         const std::string& GetLastParse();
 478         const std::vector<std::string>& GetLastParseParams() { return LastParseParams; }
 479         const std::vector<TranslateType>& GetLastParseTranslate() { return LastParseTranslate; }
 480         /** Add a mode to the mode parser.
 481          * @return True if the mode was successfully added.
 482          */
 483         bool AddMode(ModeHandler* mh);
 484         /** Delete a mode from the mode parser.
 485          * When a mode is deleted, the mode handler will be called
 486          * for every user (if it is a user mode) or for every  channel
 487          * (if it is a channel mode) to unset the mode on all objects.
 488          * This prevents modes staying in the system which no longer exist.
 489          * @param mh The mode handler to remove
 490          * @return True if the mode was successfully removed.
 491          */
 492         bool DelMode(ModeHandler* mh);
 493
 494         /** Add a mode watcher.
 495          * A mode watcher is triggered before and after a mode handler is
 496          * triggered. See the documentation of class ModeWatcher for more
 497          * information.
 498          * @param mw The ModeWatcher you want to add
 499          * @return True if the ModeWatcher was added correctly
 500          */
 501         bool AddModeWatcher(ModeWatcher* mw);
 502         /** Delete a mode watcher.
 503          * A mode watcher is triggered before and after a mode handler is
 504          * triggered. See the documentation of class ModeWatcher for more
 505          * information.
 506          * @param mw The ModeWatcher you want to delete
 507          * @return True if the ModeWatcher was deleted correctly
 508          */
 509         bool DelModeWatcher(ModeWatcher* mw);
 510         /** Process a set of mode changes from a server or user.
 511          * @param parameters The parameters of the mode change, in the format
 512          * they would be from a MODE command.
 513          * @param user The user setting or removing the modes. When the modes are set
 514          * by a server, an 'uninitialized' User is used, where *user\::nick == NULL
 515          * and *user->server == NULL.
 516          * @param merge Should the mode parameters be merged?
 517          */
 518         void Process(const std::vector<std::string>& parameters, User *user, bool merge = false);
 519
 520         /** Find the mode handler for a given mode and type.
 521          * @param modeletter mode letter to search for
 522          * @param mt type of mode to search for, user or channel
 523          * @returns a pointer to a ModeHandler class, or NULL of there isnt a handler for the given mode
 524          */
 525         ModeHandler* FindMode(unsigned const char modeletter, ModeType mt);
 526
 527         /** Find a mode handler by its prefix.
 528          * If there is no mode handler with the given prefix, NULL will be returned.
 529          * @param pfxletter The prefix to find, e.g. '@'
 530          * @return The mode handler which handles this prefix, or NULL if there is none.
 531          */
 532         ModeHandler* FindPrefix(unsigned const char pfxletter);
 533
 534         /** Returns a list of mode characters which are usermodes.
 535          * This is used in the 004 numeric when users connect.
 536          */
 537         std::string UserModeList();
 538
 539         /** Returns a list of channel mode characters which are listmodes.
 540          * This is used in the 004 numeric when users connect.
 541          */
 542         std::string ChannelModeList();
 543
 544         /** Returns a list of channel mode characters which take parameters.
 545          * This is used in the 004 numeric when users connect.
 546          */
 547         std::string ParaModeList();
 548
 549         /** Generates a list of modes, comma seperated by type:
 550          *  1; Listmodes EXCEPT those with a prefix
 551          *  2; Modes that take a param when adding or removing
 552          *  3; Modes that only take a param when adding
 553          *  4; Modes that dont take a param
 554          */
 555         std::string GiveModeList(ModeMasks m);
 556
 557         static bool PrefixComparison(ModeHandler* one, ModeHandler* two);
 558
 559         /** This returns the PREFIX=(ohv)@%+ section of the 005 numeric, or
 560          * just the "@%+" part if the parameter false
 561          */
 562         std::string BuildPrefixes(bool lettersAndModes = true);
 563 };
 564
 565 #endif