include/mode.h

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