1 /* +------------------------------------+
2 * | Inspire Internet Relay Chat Daemon |
3 * +------------------------------------+
5 * InspIRCd: (C) 2002-2010 InspIRCd Development Team
6 * See: http://wiki.inspircd.org/Credits
8 * This program is free but copyrighted software; see
9 * the file COPYING for details.
11 * ---------------------------------------------------
20 * Holds the values for different type of modes
21 * that can exist, USER or CHANNEL type.
32 * Holds mode actions - modes can be allowed or denied.
36 MODEACTION_DENY = 0, /* Drop the mode change, AND a parameter if its a parameterized mode */
37 MODEACTION_ALLOW = 1 /* Allow the mode */
41 * Used to mask off the mode types in the mode handler
42 * array. Used in a simple two instruction hashing function
43 * "(modeletter - 65) OR mask"
47 MASK_USER = 128, /* A user mode */
48 MASK_CHANNEL = 0 /* A channel mode */
52 * These fixed values can be used to proportionally compare module-defined prefixes to known values.
53 * For example, if your module queries a Channel, and is told that user 'joebloggs' has the prefix
54 * '$', and you dont know what $ means, then you can compare it to these three values to determine
55 * its worth against them. For example if '$' had a value of 15000, you would know it is of higher
56 * status than voice, but lower status than halfop.
57 * No two modes should have equal prefix values.
73 /** Parameter required on mode setting only */
75 /** Parameter always required */
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 ¶meter 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.
93 class CoreExport ModeHandler : public ServiceProvider
97 * The mode parameter translation type
99 TranslateType m_paramtype;
101 /** What kind of parameters does the mode take?
103 ParamSpec parameters_taken;
106 * The mode letter you're implementing.
110 /** Mode prefix, or 0
115 * True if the mode requires oper status
121 * Mode is a 'list' mode. The behaviour
122 * of your mode is now set entirely within
123 * the class as of the 1.1 api, rather than
124 * inside the mode parser as in the 1.0 api,
125 * so the only use of this value (along with
126 * IsListMode()) is for the core to determine
127 * wether your module can produce 'lists' or not
128 * (e.g. banlists, etc)
133 * The mode type, either MODETYPE_USER or
138 /** The prefix char needed on channel to use this mode,
139 * only checked for channel modes
145 * The constructor for ModeHandler initalizes the mode handler.
146 * The constructor of any class you derive from ModeHandler should
147 * probably call this constructor with the parameters set correctly.
148 * @param name A one-word name for the mode
149 * @param modeletter The mode letter you wish to handle
150 * @param params Parameters taken by the mode
151 * @param type Type of the mode (MODETYPE_USER or MODETYPE_CHANNEL)
153 ModeHandler(Module* me, const std::string& name, char modeletter, ParamSpec params, ModeType type);
154 virtual CullResult cull();
155 virtual ~ModeHandler();
157 * Returns true if the mode is a list mode
161 * Mode prefix or 0. If this is defined, you should
162 * also implement GetPrefixRank() to return an integer
163 * value for this mode prefix.
165 inline char GetPrefix() const { return prefix; }
167 * Get the 'value' of this modes prefix.
168 * determines which to display when there are multiple.
169 * The mode with the highest value is ranked first. See the
170 * PrefixModeValue enum and Channel::GetPrefixValue() for
173 virtual unsigned int GetPrefixRank();
175 * Returns the mode's type
177 inline ModeType GetModeType() const { return m_type; }
179 * Returns the mode's parameter translation type
181 inline TranslateType GetTranslateType() const { return m_paramtype; }
183 * Returns true if the mode can only be set/unset by an oper
185 inline bool NeedsOper() const { return oper; }
187 * Returns the number of parameters for the mode. Any non-zero
188 * value should be considered to be equivalent to one.
189 * @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.
190 * @return The number of parameters the mode expects
192 int GetNumParams(bool adding);
194 * Returns the mode character this handler handles.
195 * @return The mode character
197 inline char GetModeChar() { return mode; }
199 /** For user modes, return the current parameter, if any
201 virtual std::string GetUserParameter(User* useor);
204 * Called when a channel mode change access check for your mode occurs.
205 * @param source Contains the user setting the mode.
206 * @param channel contains the destination channel the modes are being set on.
207 * @param parameter The parameter for your mode. This is modifiable.
208 * @param adding This value is true when the mode is being set, or false when it is being unset.
209 * @return allow, deny, or passthru to check against the required level
211 virtual ModResult AccessCheck(User* source, Channel* channel, std::string ¶meter, bool adding);
214 * Called when a mode change for your mode occurs.
215 * @param source Contains the user setting the mode.
216 * @param dest For usermodes, contains the destination user the mode is being set on. For channelmodes, this is an undefined value.
217 * @param channel For channel modes, contains the destination channel the modes are being set on. For usermodes, this is an undefined value.
218 * @param parameter The parameter for your mode, if you indicated that your mode requires a parameter when being set or unset. Note that
219 * 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
220 * but you specified your mode REQUIRES a parameter, this is equivalent to returning MODEACTION_DENY and will prevent the mode from being
222 * @param adding This value is true when the mode is being set, or false when it is being unset.
223 * @return MODEACTION_ALLOW to allow the mode, or MODEACTION_DENY to prevent the mode, also see the description of 'parameter'.
225 virtual ModeAction OnModeChange(User* source, User* dest, Channel* channel, std::string ¶meter, bool adding); /* Can change the mode parameter as its a ref */
227 * If your mode is a listmode, then this method will be called for displaying an item list, e.g. on MODE #channel +modechar
228 * without any parameter or other modes in the command.
229 * @param user The user issuing the command
230 * @param channel The channel they're requesting an item list of (e.g. a banlist, or an exception list etc)
232 virtual void DisplayList(User* user, Channel* channel);
234 /** In the event that the mode should be given a parameter, and no parameter was provided, this method is called.
235 * This allows you to give special information to the user, or handle this any way you like.
236 * @param user The user issuing the mode change
237 * @param dest For user mode changes, the target of the mode. For channel mode changes, NULL.
238 * @param channel For channel mode changes, the target of the mode. For user mode changes, NULL.
240 virtual void OnParameterMissing(User* user, User* dest, Channel* channel);
243 * If your mode is a listmode, this method will be called to display an empty list (just the end of list numeric)
244 * @param user The user issuing the command
245 * @param channel The channel tehy're requesting an item list of (e.g. a banlist, or an exception list etc)
247 virtual void DisplayEmptyList(User* user, Channel* channel);
250 * If your mode needs special action during a server sync to determine which side wins when comparing timestamps,
251 * override this function and use it to return true or false. The default implementation just returns true if
252 * theirs < ours. This will only be called for non-listmodes with parameters, when adding the mode and where
253 * theirs == ours (therefore the default implementation will always return false).
254 * @param their_param Their parameter if the mode has a parameter
255 * @param our_param Our parameter if the mode has a parameter
256 * @param channel The channel we are checking against
257 * @return True if the other side wins the merge, false if we win the merge for this mode.
259 virtual bool ResolveModeConflict(std::string &their_param, const std::string &our_param, Channel* channel);
262 * When a MODETYPE_USER mode handler is being removed, the server will call this method for every user on the server.
263 * Your mode handler should remove its user mode from the user by sending the appropriate server modes using
264 * InspIRCd::SendMode(). The default implementation of this method can remove simple modes which have no parameters,
265 * and can be used when your mode is of this type, otherwise you must implement a more advanced version of it to remove
266 * your mode properly from each user.
267 * @param user The user which the server wants to remove your mode from
269 virtual void RemoveMode(User* user, irc::modestacker* stack = NULL);
272 * When a MODETYPE_CHANNEL mode handler is being removed, the server will call this method for every channel on the server.
273 * Your mode handler should remove its user mode from the channel 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 channel. Note that in the case of listmodes, you should remove the entire list of items.
277 * @param channel The channel which the server wants to remove your mode from
279 virtual void RemoveMode(Channel* channel, irc::modestacker* stack = NULL);
281 inline unsigned int GetLevelRequired() const { return levelrequired; }
284 /** A prebuilt mode handler which handles a simple user mode, e.g. no parameters, usable by any user, with no extra
285 * behaviour to the mode beyond the basic setting and unsetting of the mode, not allowing the mode to be set if it
286 * is already set and not allowing it to be unset if it is already unset.
287 * An example of a simple user mode is user mode +w.
289 class CoreExport SimpleUserModeHandler : public ModeHandler
292 SimpleUserModeHandler(Module* Creator, const std::string& Name, char modeletter)
293 : ModeHandler(Creator, Name, modeletter, PARAM_NONE, MODETYPE_USER) {}
294 virtual ~SimpleUserModeHandler() {}
295 virtual ModeAction OnModeChange(User* source, User* dest, Channel* channel, std::string ¶meter, bool adding);
298 /** A prebuilt mode handler which handles a simple channel mode, e.g. no parameters, usable by any user, with no extra
299 * behaviour to the mode beyond the basic setting and unsetting of the mode, not allowing the mode to be set if it
300 * is already set and not allowing it to be unset if it is already unset.
301 * An example of a simple channel mode is channel mode +s.
303 class CoreExport SimpleChannelModeHandler : public ModeHandler
306 SimpleChannelModeHandler(Module* Creator, const std::string& Name, char modeletter)
307 : ModeHandler(Creator, Name, modeletter, PARAM_NONE, MODETYPE_CHANNEL) {}
308 virtual ~SimpleChannelModeHandler() {}
309 virtual ModeAction OnModeChange(User* source, User* dest, Channel* channel, std::string ¶meter, bool adding);
312 class CoreExport ParamChannelModeHandler : public ModeHandler
315 ParamChannelModeHandler(Module* Creator, const std::string& Name, char modeletter)
316 : ModeHandler(Creator, Name, modeletter, PARAM_SETONLY, MODETYPE_CHANNEL) {}
317 virtual ModeAction OnModeChange(User* source, User* dest, Channel* channel, std::string ¶meter, bool adding);
318 /** Validate the parameter - you may change the value to normalize it. Return true if it is valid. */
319 virtual bool ParamValidate(std::string& parameter);
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.
328 class CoreExport ModeWatcher : public classbase
332 * The mode letter this class is watching
336 * The mode type being watched (user or channel)
343 * The constructor initializes the mode and the mode type
345 ModeWatcher(Module* creator, char modeletter, ModeType type);
347 * The default destructor does nothing.
349 virtual ~ModeWatcher();
352 * Get the mode character being watched
353 * @return The mode character being watched
357 * Get the mode type being watched
358 * @return The mode type being watched (user or channel)
360 ModeType GetModeType();
363 * Before the mode character is processed by its handler, this method will be called.
364 * @param source The sender of the mode
365 * @param dest The target user for the mode, if you are watching a user mode
366 * @param channel The target channel for the mode, if you are watching a channel mode
367 * @param parameter The parameter of the mode, if the mode is supposed to have a parameter.
368 * If you alter the parameter you are given, the mode handler will see your atered version
369 * when it handles the mode.
370 * @param adding True if the mode is being added and false if it is being removed
371 * @type The mode type, either MODETYPE_USER or MODETYPE_CHANNEL
372 * @return True to allow the mode change to go ahead, false to abort it. If you abort the
373 * change, the mode handler (and ModeWatcher::AfterMode()) will never see the mode change.
375 virtual bool BeforeMode(User* source, User* dest, Channel* channel, std::string ¶meter, bool adding, ModeType type);
377 * After the mode character has been processed by the ModeHandler, this method will be called.
378 * @param source The sender of the mode
379 * @param dest The target user for the mode, if you are watching a user mode
380 * @param channel The target channel for the mode, if you are watching a channel mode
381 * @param parameter The parameter of the mode, if the mode is supposed to have a parameter.
382 * You cannot alter the parameter here, as the mode handler has already processed it.
383 * @param adding True if the mode is being added and false if it is being removed
384 * @type The mode type, either MODETYPE_USER or MODETYPE_CHANNEL
386 virtual void AfterMode(User* source, User* dest, Channel* channel, const std::string ¶meter, bool adding, ModeType type);
389 typedef std::vector<ModeWatcher*>::iterator ModeWatchIter;
391 /** The mode parser handles routing of modes and handling of mode strings.
392 * It marshalls, controls and maintains both ModeWatcher and ModeHandler classes,
393 * parses client to server MODE strings for user and channel modes, and performs
394 * processing for the 004 mode list numeric, amongst other things.
396 class CoreExport ModeParser
399 /** Mode handlers for each mode, to access a handler subtract
400 * 65 from the ascii value of the mode letter.
401 * The upper bit of the value indicates if its a usermode
402 * or a channel mode, so we have 256 of them not 64.
404 ModeHandler* modehandlers[256];
405 /** Mode watcher classes arranged in the same way as the
406 * mode handlers, except for instead of having 256 of them
407 * we have 256 lists of them.
409 std::vector<ModeWatcher*> modewatchers[256];
410 /** Displays the current modes of a channel or user.
411 * Used by ModeParser::Process.
413 void DisplayCurrentModes(User *user, User* targetuser, Channel* targetchannel, const char* text);
414 /** Displays the value of a list mode
415 * Used by ModeParser::Process.
417 void DisplayListModes(User* user, Channel* chan, std::string &mode_sequence);
420 * Attempts to apply a mode change to a user or channel
422 ModeAction TryMode(User* user, User* targu, Channel* targc, bool adding, unsigned char mode, std::string ¶m, bool SkipACL);
424 /** The string representing the last set of modes to be parsed.
425 * Use GetLastParse() to get this value, to be used for display purposes.
427 std::string LastParse;
428 std::vector<std::string> LastParseParams;
429 std::vector<TranslateType> LastParseTranslate;
431 unsigned int sent[256];
437 /** The constructor initializes all the RFC basic modes by using ModeParserAddMode().
442 /** Used to check if user 'd' should be allowed to do operation 'MASK' on channel 'chan'.
443 * for example, should 'user A' be able to 'op' on 'channel B'.
445 User* SanityChecks(User *user,const char *dest,Channel *chan,int status);
446 /** Tidy a banmask. This makes a banmask 'acceptable' if fields are left out.
451 * nick!ident -> nick!ident@*
453 * host.name -> *!*@host.name
455 * ident@host.name -> *!ident@host.name
457 * This method can be used on both IPV4 and IPV6 user masks.
459 static void CleanMask(std::string &mask);
460 /** Get the last string to be processed, as it was sent to the user or channel.
461 * Use this to display a string you just sent to be parsed, as the actual output
462 * may be different to what you sent after it has been 'cleaned up' by the parser.
463 * @return Last parsed string, as seen by users.
465 const std::string& GetLastParse();
466 const std::vector<std::string>& GetLastParseParams() { return LastParseParams; }
467 const std::vector<TranslateType>& GetLastParseTranslate() { return LastParseTranslate; }
468 /** Add a mode to the mode parser.
469 * @return True if the mode was successfully added.
471 bool AddMode(ModeHandler* mh);
472 /** Delete a mode from the mode parser.
473 * When a mode is deleted, the mode handler will be called
474 * for every user (if it is a user mode) or for every channel
475 * (if it is a channel mode) to unset the mode on all objects.
476 * This prevents modes staying in the system which no longer exist.
477 * @param mh The mode handler to remove
478 * @return True if the mode was successfully removed.
480 bool DelMode(ModeHandler* mh);
482 /** Add a mode watcher.
483 * A mode watcher is triggered before and after a mode handler is
484 * triggered. See the documentation of class ModeWatcher for more
486 * @param mw The ModeWatcher you want to add
487 * @return True if the ModeWatcher was added correctly
489 bool AddModeWatcher(ModeWatcher* mw);
490 /** Delete a mode watcher.
491 * A mode watcher is triggered before and after a mode handler is
492 * triggered. See the documentation of class ModeWatcher for more
494 * @param mw The ModeWatcher you want to delete
495 * @return True if the ModeWatcher was deleted correctly
497 bool DelModeWatcher(ModeWatcher* mw);
498 /** Process a set of mode changes from a server or user.
499 * @param parameters The parameters of the mode change, in the format
500 * they would be from a MODE command.
501 * @param user The user setting or removing the modes. When the modes are set
502 * by a server, an 'uninitialized' User is used, where *user::nick == NULL
503 * and *user->server == NULL.
505 void Process(const std::vector<std::string>& parameters, User *user, bool merge = false);
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
512 ModeHandler* FindMode(unsigned const char modeletter, ModeType mt);
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.
519 ModeHandler* FindPrefix(unsigned const char pfxletter);
521 /** Returns a list of mode characters which are usermodes.
522 * This is used in the 004 numeric when users connect.
524 std::string UserModeList();
526 /** Returns a list of channel mode characters which are listmodes.
527 * This is used in the 004 numeric when users connect.
529 std::string ChannelModeList();
531 /** Returns a list of channel mode characters which take parameters.
532 * This is used in the 004 numeric when users connect.
534 std::string ParaModeList();
536 /** Generates a list of modes, comma seperated by type:
537 * 1; Listmodes EXCEPT those with a prefix
538 * 2; Modes that take a param when adding or removing
539 * 3; Modes that only take a param when adding
540 * 4; Modes that dont take a param
542 std::string GiveModeList(ModeMasks m);
544 static bool PrefixComparison(ModeHandler* one, ModeHandler* two);
546 /** This returns the PREFIX=(ohv)@%+ section of the 005 numeric, or
547 * just the "@%+" part if the parameter false
549 std::string BuildPrefixes(bool lettersAndModes = true);