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