From 49e34a508d9070097fa6aae5bf611bdd5c2b0f2d Mon Sep 17 00:00:00 2001 From: brain Date: Tue, 9 Jan 2007 22:31:19 +0000 Subject: Comment on a lot of recently added stuff that wasnt properly documented (until now) git-svn-id: http://svn.inspircd.org/repository/trunk/inspircd@6284 e03df62e-2008-0410-955e-edbf42e46eb7 --- include/ctables.h | 53 +++++++++++++++++++++++++++++++++++++++++++++- include/dns.h | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++---- include/timer.h | 24 +++++++++++++++++++++ include/users.h | 58 +++++++++++++++++++++++++++++++++++++++++++++++--- 4 files changed, 190 insertions(+), 8 deletions(-) diff --git a/include/ctables.h b/include/ctables.h index 7d1173307..9eae05257 100644 --- a/include/ctables.h +++ b/include/ctables.h @@ -41,11 +41,14 @@ enum CmdResult #define CMD_LOCALONLY CMD_FAILURE -/** A structure that defines a command +/** A structure that defines a command. Every command available + * in InspIRCd must be defined as derived from command_t. */ class command_t : public Extensible { protected: + /** Owner/Creator object + */ InspIRCd* ServerInstance; public: /** Command name @@ -77,6 +80,16 @@ class command_t : public Extensible */ std::string syntax; + /** Create a new command. + * @param Instance Pointer to creator class + * @param cmd Command name. This must be UPPER CASE. + * @param flags User modes required to execute the command. + * For oper only commands, set this to 'o', otherwise use 0. + * @param minpara Minimum parameters required for the command. + * @param before_reg If this is set to true, the command will + * be allowed before the user is 'registered' (has sent USER, + * NICK, optionally PASS, and been resolved). + */ command_t(InspIRCd* Instance, const std::string &cmd, char flags, int minpara, int before_reg = false) : ServerInstance(Instance), command(cmd), flags_needed(flags), min_params(minpara), disabled(false), works_before_reg(before_reg) { use_count = total_bytes = 0; @@ -84,36 +97,74 @@ class command_t : public Extensible syntax = ""; } + /** Handle the command from a user. + * @param parameters The parameters for the command. + * @param pcnt The number of parameters available in 'parameters' + * @param user The user who issued the command. + * @return Return CMD_SUCCESS on success, or CMD_FAILURE on failure. + * If the command succeeds but should remain local to this server, + * return CMD_LOCALONLY. + */ virtual CmdResult Handle(const char** parameters, int pcnt, userrec* user) = 0; + /** Handle an internal request from another command, the core, or a module + * @param Command ID + * @param Zero or more parameters, whos form is specified by the command ID. + * @return Return CMD_SUCCESS on success, or CMD_FAILURE on failure. + * If the command succeeds but should remain local to this server, + * return CMD_LOCALONLY. + */ virtual CmdResult HandleInternal(const unsigned int id, const std::deque ¶ms) { return CMD_INVALID; } + /** Handle the command from a server. + * Not currently used in this version of InspIRCd. + * @param parameters The parameters given + * @param pcnt The number of parameters available + * @param servername The server name which issued the command + * @return Return CMD_SUCCESS on success, or CMD_FAILURE on failure. + * If the command succeeds but should remain local to this server, + * return CMD_LOCALONLY. + */ virtual CmdResult HandleServer(const char** parameters, int pcnt, const std::string &servername) { return CMD_INVALID; } + /** Disable or enable this command. + * @param setting True to disable the command. + */ void Disable(bool setting) { disabled = setting; } + /** Obtain this command's disable state. + * @return true if the command is currently disabled + * (disabled commands can be used only by operators) + */ bool IsDisabled() { return disabled; } + /** @return true if the command works before registration. + */ bool WorksBeforeReg() { return works_before_reg; } + /** Standard constructor gubbins + */ virtual ~command_t() {} }; +/** A hash of commands used by the core + */ typedef nspace::hash_map command_table; #endif + diff --git a/include/dns.h b/include/dns.h index 562a49322..6913527ae 100644 --- a/include/dns.h +++ b/include/dns.h @@ -55,11 +55,25 @@ class Module; class DNSResult : public classbase { public: + /** Result ID + */ int id; + /** Result body, a hostname or IP address + */ std::string result; + /** Time-to-live value of the result + */ unsigned long ttl; + /** The original request, a hostname or IP address + */ std::string original; + /** Build a DNS result. + * @param i The request ID + * @param res The request result, a hostname or IP + * @param timetolive The request time-to-live + * @param orig The original request, a hostname or IP + */ DNSResult(int i, const std::string &res, unsigned long timetolive, const std::string &orig) : id(i), result(res), ttl(timetolive), original(orig) { } }; @@ -68,19 +82,30 @@ class DNSResult : public classbase */ typedef std::pair DNSInfo; -/** Cached item +/** Cached item stored in the query cache. */ class CachedQuery { public: + /** The cached result data, an IP or hostname + */ std::string data; + /** The time when the item is due to expire + */ time_t expires; + /** Build a cached query + * @param res The result data, an IP or hostname + * @param ttl The time-to-live value of the query result + */ CachedQuery(const std::string &res, unsigned int ttl) : data(res) { expires = time(NULL) + ttl; } + /** Returns the number of seconds remaining before this + * cache item has expired and should be removed. + */ int CalcTTLRemaining() { int n = expires - time(NULL); @@ -88,7 +113,7 @@ class CachedQuery } }; -/** DNS cache information +/** DNS cache information. Holds IPs mapped to hostnames, and hostnames mapped to IPs. */ typedef nspace::hash_map > dnscache; @@ -277,12 +302,15 @@ class Resolver : public Extensible * this method will return -1. */ int GetId(); - /** * Returns the creator module, or NULL */ Module* GetCreator(); - + /** + * If the result is a cached result, this triggers the objects + * OnLookupComplete. This is done because it is not safe to call + * the abstract virtual method from the constructor. + */ void TriggerCachedResult(); }; @@ -295,6 +323,9 @@ class DNS : public EventHandler { private: + /** + * Creator/Owner object + */ InspIRCd* ServerInstance; /** @@ -326,6 +357,9 @@ class DNS : public EventHandler */ dnscache* cache; + /** A timer which ticks every hour to remove expired + * items from the DNS cache. + */ class CacheTimer* PruneTimer; /** @@ -334,14 +368,17 @@ class DNS : public EventHandler int MakePayload(const char* name, const QueryType rr, const unsigned short rr_class, unsigned char* payload); public: + /** * Currently active Resolver classes */ Resolver* Classes[MAX_REQUEST_ID]; + /** * Requests that are currently 'in flight' */ DNSRequest* requests[MAX_REQUEST_ID]; + /** * The port number DNS requests are made on, * and replies have as a source-port number. @@ -352,14 +389,17 @@ class DNS : public EventHandler * Fill an rr (resource record) with data from input */ static void FillResourceRecord(ResourceRecord* rr, const unsigned char* input); + /** * Fill a header with data from input limited by a length */ static void FillHeader(DNSHeader *header, const unsigned char *input, const int length); + /** * Empty out a header into a data stream ready for transmission "on the wire" */ static void EmptyHeader(unsigned char *output, const DNSHeader *header, const int length); + /** * Start the lookup of an ipv4 from a hostname */ @@ -447,11 +487,26 @@ class DNS : public EventHandler */ void CleanResolvers(Module* module); + /** Return the cached value of an IP or hostname + * @param source An IP or hostname to find in the cache. + * @return A pointer to a CachedQuery if the item exists, + * otherwise NULL. + */ CachedQuery* GetCache(const std::string &source); + /** Delete a cached item from the DNS cache. + * @param source An IP or hostname to remove + */ void DelCache(const std::string &source); + /** Clear all items from the DNS cache immediately. + */ int ClearCache(); + + /** Prune the DNS cache, e.g. remove all expired + * items and rehash the cache buckets, but leave + * items in the hash which are still valid. + */ int PruneCache(); }; diff --git a/include/timer.h b/include/timer.h index 9820be2fb..2d12d84e5 100644 --- a/include/timer.h +++ b/include/timer.h @@ -30,7 +30,11 @@ class InspTimer : public Extensible /** The triggering time */ time_t trigger; + /** Number of seconds between triggers + */ long secs; + /** True if this is a repeating timer + */ bool repeat; public: /** Default constructor, initializes the triggering time @@ -44,29 +48,49 @@ class InspTimer : public Extensible secs = secs_from_now; repeat = repeating; } + /** Default destructor, does nothing. */ virtual ~InspTimer() { } + /** Retrieve the current triggering time */ virtual time_t GetTimer() { return trigger; } + /** Called when the timer ticks. + * You should override this method with some useful code to + * handle the tick event. */ virtual void Tick(time_t TIME) = 0; + /** Returns true if this timer is set to repeat + */ bool GetRepeat() { return repeat; } + /** Returns the interval (number of seconds between ticks) + * of this timer object. + */ long GetSecs() { return secs; } + /** Cancels the repeat state of a repeating timer. + * If you call this method, then the next time your + * timer ticks, it will be removed immediately after. + * You should use this method call to remove a recurring + * timer if you wish to do so within the timer's Tick + * event, as calling TimerManager::DelTimer() from within + * the InspTimer::Tick() method is dangerous and may + * cause a segmentation fault. Calling CancelRepeat() + * is safe in this case. + */ void CancelRepeat() { repeat = false; diff --git a/include/users.h b/include/users.h index d69781f80..bfe21f116 100644 --- a/include/users.h +++ b/include/users.h @@ -120,68 +120,107 @@ class ConnectClass : public classbase public: + /** Create a new connect class with no settings. + */ ConnectClass() : type(CC_DENY), registration_timeout(0), flood(0), host(""), pingtime(0), pass(""), threshold(0), sendqmax(0), recvqmax(0), maxlocal(0), maxglobal(0) { } + /** Create a new connect class to ALLOW connections. + * @param timeout The registration timeout + * @param fld The flood value + * @param hst The IP mask to allow + * @param ping The ping frequency + * @param pas The password to be used + * @param thres The flooding threshold + * @param sendq The maximum sendq value + * @param recvq The maximum recvq value + * @param maxl The maximum local sessions + * @param maxg The maximum global sessions + */ ConnectClass(unsigned int timeout, unsigned int fld, const std::string &hst, unsigned int ping, const std::string &pas, unsigned int thres, unsigned long sendq, unsigned long recvq, unsigned long maxl, unsigned long maxg) : type(CC_ALLOW), registration_timeout(timeout), flood(fld), host(hst), pingtime(ping), pass(pas), threshold(thres), sendqmax(sendq), recvqmax(recvq), maxlocal(maxl), maxglobal(maxg) { } + /** Create a new connect class to DENY connections + * @param hst The IP mask to deny + */ ConnectClass(const std::string &hst) : type(CC_DENY), registration_timeout(0), flood(0), host(hst), pingtime(0), pass(""), threshold(0), sendqmax(0), recvqmax(0), maxlocal(0), maxglobal(0) { } + /** Returns the type, CC_ALLOW or CC_DENY + */ char GetType() { return (type == CC_ALLOW ? CC_ALLOW : CC_DENY); } + /** Returns the registration timeout + */ unsigned int GetRegTimeout() { return (registration_timeout ? registration_timeout : 90); } + /** Returns the flood limit + */ unsigned int GetFlood() { return (threshold ? flood : 999); } + /** Returns the allowed or denied IP mask + */ const std::string& GetHost() { return host; } + /** Returns the ping frequency + */ unsigned int GetPingTime() { return (pingtime ? pingtime : 120); } + /** Returns the password or an empty string + */ const std::string& GetPass() { return pass; } + /** Returns the flood threshold value + */ unsigned int GetThreshold() { return (threshold ? threshold : 1); } + /** Returns the maximum sendq value + */ unsigned long GetSendqMax() { return (sendqmax ? sendqmax : 262114); } + /** Returns the maximum recvq value + */ unsigned long GetRecvqMax() { return (recvqmax ? recvqmax : 4096); } + /** Returusn the maximum number of local sessions + */ unsigned long GetMaxLocal() { return (maxlocal ? maxlocal : 1); } + /** Returns the maximum number of global sessions + */ unsigned long GetMaxGlobal() { return (maxglobal ? maxglobal : 1); @@ -227,8 +266,16 @@ class userrec : public connection */ unsigned int ChannelCount; + /** Cached nick!ident@host value using the real hostname + */ char* cached_fullhost; + + /** Cached nick!ident@ip value using the real IP address + */ char* cached_hostip; + + /** Cached nick!ident@host value using the masked hostname + */ char* cached_makehost; char* cached_fullrealhost; @@ -368,7 +415,8 @@ class userrec : public connection */ long threshold; - /** IPV4 or IPV6 ip address + /** IPV4 or IPV6 ip address. Use SetSockAddr to set this and GetProtocolFamily/ + * GetIPString/GetPort to obtain its values. */ sockaddr* ip; @@ -404,11 +452,13 @@ class userrec : public connection */ std::string WriteError; - /** Maximum size this user's sendq can become + /** Maximum size this user's sendq can become. + * Copied from the connect class on connect. */ long sendqmax; - /** Maximum size this user's recvq can become + /** Maximum size this user's recvq can become. + * Copied from the connect class on connect. */ long recvqmax; @@ -838,6 +888,8 @@ class userrec : public connection /** Handle socket event. * From EventHandler class. + * @param et Event type + * @param errornum Error number for EVENT_ERROR events */ void HandleEvent(EventType et, int errornum = 0); -- cgit v1.2.3