diff options
| -rw-r--r-- | include/xline.h | 180 |
1 files changed, 152 insertions, 28 deletions
diff --git a/include/xline.h b/include/xline.h index 32ae04d5a..74c58e05c 100644 --- a/include/xline.h +++ b/include/xline.h @@ -14,28 +14,30 @@ #ifndef __XLINE_H #define __XLINE_H -// include the common header files - #include <string> #include <deque> #include <vector> #include "users.h" #include "channels.h" -const int APPLY_GLINES = 1; -const int APPLY_KLINES = 2; -const int APPLY_QLINES = 4; -const int APPLY_ZLINES = 8; -const int APPLY_PERM_ONLY = 16; -const int APPLY_ALL = APPLY_GLINES | APPLY_KLINES | APPLY_QLINES | APPLY_ZLINES; - /** XLine is the base class for ban lines such as G lines and K lines. + * Modules may derive from this, and their xlines will automatically be + * handled as expected by any protocol modules (e.g. m_spanningtree will + * propogate them using AddLine). The process of translating a type+pattern + * to a known line type is done by means of an XLineFactory object (see + * below). */ class CoreExport XLine : public classbase { protected: + /** Creator */ InspIRCd* ServerInstance; + + /** Default 'apply' action. Quits the user. + * @param u User to apply the line against + * @param line The line typed, used for display purposes in the quit message + */ void DefaultApply(User* u, const std::string &line); public: @@ -45,6 +47,7 @@ class CoreExport XLine : public classbase * @param d The duration of the xline * @param src The sender of the xline * @param re The reason of the xline + * @param t The line type, should be set by the derived class constructor */ XLine(InspIRCd* Instance, time_t s_time, long d, const char* src, const char* re, const std::string &t) : ServerInstance(Instance), set_time(s_time), duration(d), type(t) @@ -62,6 +65,9 @@ class CoreExport XLine : public classbase free(source); } + /** Change creation time of an xline. Updates expiry + * to be after the creation time + */ virtual void SetCreateTime(time_t created) { set_time = created; @@ -69,19 +75,48 @@ class CoreExport XLine : public classbase } /** Returns true whether or not the given user is covered by this line. + * @param u The user to match against. The mechanics of the match + * are defined by the derived class. + * @return True if there is a match. */ virtual bool Matches(User *u) = 0; + /** Returns true whether or not the given string is covered by this line. + * @param str The string to match against. The details of what must be + * in this string and the mechanics of the match are defined by the + * derived class. + * @return True if there is a match + */ virtual bool Matches(const std::string &str) = 0; + /** Apply a line against a user. The mechanics of what occurs when + * the line is applied are specific to the derived class. + * @param u The user to apply against + */ virtual void Apply(User* u); + /** Called when the line is unset either via expiry or + * via explicit removal. + */ virtual void Unset() { } + /** Called when the expiry message is to be displayed for the + * line. Usually a line in the form 'expiring Xline blah, set by...' + * see the DisplayExpiry methods of GLine, ELine etc. + */ virtual void DisplayExpiry() = 0; + /** Returns the displayable form of the pattern for this xline, + * e.g. '*@foo' or '*baz*'. This must always return the full pattern + * in a form which can be used to construct an entire derived xline, + * even if it is stored differently internally (e.g. GLine stores the + * ident and host parts seperately but will still return ident@host + * for its Displayable() method) + */ virtual const char* Displayable() = 0; + /** Called when the xline has just been added. + */ virtual void OnAdd() { } /** The time the line was added. @@ -100,11 +135,12 @@ class CoreExport XLine : public classbase */ char* reason; - /** Expiry time + /** Expiry time. Does not contain useful data if the duration is 0. */ time_t expiry; - /** Q, K, etc. Don't change this. Constructors set it. + /** "Q", "K", etc. Set only by derived classes constructor to the + * type of line this is. */ const std::string type; }; @@ -114,6 +150,7 @@ class CoreExport XLine : public classbase class CoreExport KLine : public XLine { public: + /** Create a K-Line. * @param s_time The set time * @param d The duration of the xline @@ -148,10 +185,10 @@ class CoreExport KLine : public XLine virtual const char* Displayable(); - /** Ident mask + /** Ident mask (ident part only) */ char* identmask; - /** Host mask + /** Host mask (host part only) */ char* hostmask; @@ -197,10 +234,10 @@ class CoreExport GLine : public XLine virtual const char* Displayable(); - /** Ident mask + /** Ident mask (ident part only) */ char* identmask; - /** Host mask + /** Host mask (host part only) */ char* hostmask; @@ -246,10 +283,10 @@ class CoreExport ELine : public XLine virtual const char* Displayable(); - /** Ident mask + /** Ident mask (ident part only) */ char* identmask; - /** Host mask + /** Host mask (host part only) */ char* hostmask; @@ -290,7 +327,7 @@ class CoreExport ZLine : public XLine virtual const char* Displayable(); - /** IP mask + /** IP mask (no ident part) */ char* ipaddr; }; @@ -338,7 +375,13 @@ class CoreExport QLine : public XLine */ typedef std::pair<std::string, std::string> IdentHostPair; - +/** XLineFactory is used to generate an XLine pointer, given just the + * pattern, timing information and type of line to create. This is used + * for example in the spanningtree module which will call an XLineFactory + * to create a new XLine when it is inbound on a server link, so that it + * does not have to know the specifics of the internals of an XLine class + * and/or how to call its constructor. + */ class CoreExport XLineFactory { protected: @@ -348,12 +391,29 @@ class CoreExport XLineFactory public: + /** Create an XLine factory + * @param Instance creator + * @param t Type of XLine this factory generates + */ XLineFactory(InspIRCd* Instance, const std::string &t) : ServerInstance(Instance), type(t) { } + /** Return the type of XLine this factory generates + * @return The type of XLine this factory generates + */ virtual const std::string& GetType() { return type; } + /** Generate a specialized XLine*. + * @param set_time Time this line was created + * @param duration Duration of the line + * @param source The sender of the line, nickname or server + * @param reason The reason for the line + * @param xline_specific_mask The mask string for the line, specific to the XLine type being created. + * @return A specialized XLine class of the given type for this factory. + */ virtual XLine* Generate(time_t set_time, long duration, const char* source, const char* reason, const char* xline_specific_mask) = 0; + /** Destructor + */ virtual ~XLineFactory() { } }; @@ -368,13 +428,29 @@ class QLineFactory; class ZLineFactory; class KLineFactory; +/** A map of xline factories + */ typedef std::map<std::string, XLineFactory*> XLineFactMap; + +/** A map of XLines indexed by string + */ typedef std::map<std::string, XLine *> XLineLookup; + +/** A map of XLineLookup maps indexed by string + */ typedef std::map<std::string, XLineLookup > XLineContainer; + +/** An iterator in an XLineContainer + */ typedef XLineContainer::iterator ContainerIter; + +/** An interator in an XLineLookup + */ typedef XLineLookup::iterator LookupIter; -/** XLineManager is a class used to manage glines, klines, elines, zlines and qlines. +/** XLineManager is a class used to manage glines, klines, elines, zlines and qlines, + * or any other line created by a module. It also manages XLineFactory classes which + * can generate a specialized XLine for use by another module. */ class CoreExport XLineManager { @@ -387,14 +463,25 @@ class CoreExport XLineManager */ std::vector<XLine *> pending_lines; + /** Current xline factories + */ XLineFactMap line_factory; + /** Core xline factories for G/E/K/Q/Z lines + * (These generate GLine, ELine, KLine, QLine and ZLine + * respectively) + */ GLineFactory* GFact; ELineFactory* EFact; KLineFactory* KFact; QLineFactory* QFact; ZLineFactory* ZFact; + /** Container of all lines, this is a map of maps which + * allows for fast lookup for add/remove of a line, and + * the shortest possible timed O(n) for checking a user + * against a line. + */ XLineContainer lookup_lines; public: @@ -404,6 +491,8 @@ class CoreExport XLineManager */ XLineManager(InspIRCd* Instance); + /** Destructor + */ ~XLineManager(); /** Split an ident and host into two seperate strings. @@ -415,22 +504,27 @@ class CoreExport XLineManager */ void CheckELines(); - /** Get all lines of a certain type to an XLineLookup (std::map<std::string, XLine*>) + /** Get all lines of a certain type to an XLineLookup (std::map<std::string, XLine*>). + * NOTE: When this function runs any expired items are removed from the list before it + * is returned to the caller. + * @param The type to look up + * @return A list of all XLines of the given type. */ XLineLookup* GetAll(const std::string &type); - /** Return all known types of line currently stored by the XLineManager + /** Return all known types of line currently stored by the XLineManager. + * @return A vector containing all known line types currently stored in the main list. */ std::vector<std::string> GetAllTypes(); - /** Add a new GLine + /** Add a new XLine * @param line The line to be added * @param user The user adding the line or NULL for the local server * @return True if the line was added successfully */ bool AddLine(XLine* line, User* user); - /** Delete a GLine + /** Delete an XLine * @param hostmask The xline-specific string identifying the line, e.g. "*@foo" * @param type The type of xline * @param user The user removing the line or NULL if its the local server @@ -447,15 +541,19 @@ class CoreExport XLineManager * you do not know the full details of the item you wish to create, e.g. in a * server protocol module like m_spanningtree, when you receive xlines from other * servers. + * @param xlf XLineFactory pointer to register */ bool RegisterFactory(XLineFactory* xlf); - /** Unregisters an xline factory + /** Unregisters an xline factory. + * You must do this when your module unloads. + * @param xlf XLineFactory pointer to unregister */ bool UnregisterFactory(XLineFactory* xlf); /** Get the XLineFactory for a specific type. - * Returns NULL if there is no known handler for this xline type + * Returns NULL if there is no known handler for this xline type. + * @param type The type of XLine you require the XLineFactory for */ XLineFactory* GetFactory(const std::string &type); @@ -473,15 +571,21 @@ class CoreExport XLineManager */ XLine* MatchesLine(const std::string &type, const std::string &pattern); - /** Expire a line given two iterators which identify it + /** Expire a line given two iterators which identify it in the main map. + * @param container Iterator to the first level of entries the map + * @param item Iterator to the second level of entries in the map */ void ExpireLine(ContainerIter container, LookupIter item); - /** Apply any new lines that are pending to be applied + /** Apply any new lines that are pending to be applied. + * This will only apply lines in the pending_lines list, to save on + * CPU time. */ void ApplyLines(); /** Handle /STATS for a given type. + * NOTE: Any items in the list for this particular line type which have expired + * will be expired and removed before the list is displayed. * @param numeric The numeric to give to each result line * @param user The username making the query * @param results The string_list to receive the results @@ -489,11 +593,15 @@ class CoreExport XLineManager void InvokeStats(const std::string &type, int numeric, User* user, string_list &results); }; +/** An XLineFactory specialized to generate GLine* pointers + */ class CoreExport GLineFactory : public XLineFactory { public: GLineFactory(InspIRCd* Instance) : XLineFactory(Instance, "G") { } + /** Generate a GLine + */ XLine* Generate(time_t set_time, long duration, const char* source, const char* reason, const char* xline_specific_mask) { IdentHostPair ih = ServerInstance->XLines->IdentSplit(xline_specific_mask); @@ -501,11 +609,15 @@ class CoreExport GLineFactory : public XLineFactory } }; +/** An XLineFactory specialized to generate ELine* pointers + */ class CoreExport ELineFactory : public XLineFactory { public: ELineFactory(InspIRCd* Instance) : XLineFactory(Instance, "E") { } + /** Generate an ELine + */ XLine* Generate(time_t set_time, long duration, const char* source, const char* reason, const char* xline_specific_mask) { IdentHostPair ih = ServerInstance->XLines->IdentSplit(xline_specific_mask); @@ -513,11 +625,15 @@ class CoreExport ELineFactory : public XLineFactory } }; +/** An XLineFactory specialized to generate KLine* pointers + */ class CoreExport KLineFactory : public XLineFactory { public: KLineFactory(InspIRCd* Instance) : XLineFactory(Instance, "K") { } + /** Generate a KLine + */ XLine* Generate(time_t set_time, long duration, const char* source, const char* reason, const char* xline_specific_mask) { IdentHostPair ih = ServerInstance->XLines->IdentSplit(xline_specific_mask); @@ -525,22 +641,30 @@ class CoreExport KLineFactory : public XLineFactory } }; +/** An XLineFactory specialized to generate QLine* pointers + */ class CoreExport QLineFactory : public XLineFactory { public: QLineFactory(InspIRCd* Instance) : XLineFactory(Instance, "Q") { } + /** Generate a QLine + */ XLine* Generate(time_t set_time, long duration, const char* source, const char* reason, const char* xline_specific_mask) { return new QLine(ServerInstance, set_time, duration, source, reason, xline_specific_mask); } }; +/** An XLineFactory specialized to generate ZLine* pointers + */ class CoreExport ZLineFactory : public XLineFactory { public: ZLineFactory(InspIRCd* Instance) : XLineFactory(Instance, "Z") { } + /** Generate a ZLine + */ XLine* Generate(time_t set_time, long duration, const char* source, const char* reason, const char* xline_specific_mask) { return new ZLine(ServerInstance, set_time, duration, source, reason, xline_specific_mask); |