From: brain Date: Tue, 8 Aug 2006 16:34:24 +0000 (+0000) Subject: Tons of comments X-Git-Tag: v2.0.23~7506 X-Git-Url: https://git.netwichtig.de/gitweb/?a=commitdiff_plain;h=861ca7f2fe22c95cbbdbe534ba6477cc5f8baaf3;p=user%2Fhenk%2Fcode%2Finspircd.git Tons of comments git-svn-id: http://svn.inspircd.org/repository/trunk/inspircd@4796 e03df62e-2008-0410-955e-edbf42e46eb7 --- diff --git a/include/users.h b/include/users.h index a01b0f28b..30111870d 100644 --- a/include/users.h +++ b/include/users.h @@ -164,9 +164,18 @@ class userrec : public connection /** Resolvers for looking up this users hostname */ UserResolver* res_forward; + + /** Resolvers for looking up this users hostname + */ UserResolver* res_reverse; + + /** Stored reverse lookup from res_forward + */ std::string stored_host; + /** Starts a DNS lookup of the user's IP. + * When complete, sets userrec::dns_done to true. + */ void StartDNSLookup(); /** The users nickname. @@ -205,6 +214,8 @@ class userrec : public connection */ char snomasks[64]; + /** Channels this user is on, and the permissions they have there + */ UserChanList chans; /** The server the user is connected to. @@ -271,22 +282,30 @@ class userrec : public connection sockaddr* ip; /** Initialize the clients sockaddr + * @param protocol_family The protocol family of the IP address, AF_INET or AF_INET6 + * @param ip A human-readable IP address for this user matching the protcol_family + * @param port The port number of this user or zero for a remote user */ void SetSockAddr(int protocol_family, const char* ip, int port); /** Get port number from sockaddr + * @return The port number of this user. */ int GetPort(); /** Get protocol family from sockaddr + * @return The protocol family of this user, either AF_INET or AF_INET6 */ int GetProtocolFamily(); /** Get IP string from sockaddr, using static internal buffer + * @return The IP string */ const char* GetIPString(); /** Get IP string from sockaddr, using caller-specified buffer + * @param buf A buffer to use + * @return The IP string */ const char* GetIPString(char* buf); @@ -303,12 +322,14 @@ class userrec : public connection long recvqmax; /** Default constructor + * @throw Nothing at present */ userrec(); /** Returns the full displayed host of the user * This member function returns the hostname of the user as seen by other users * on the server, in nick!ident&at;host form. + * @return The full masked host of the user */ virtual char* GetFullHost(); @@ -316,64 +337,97 @@ class userrec : public connection * This member function returns the hostname of the user as seen by other users * on the server, in nick!ident&at;host form. If any form of hostname cloaking is in operation, * e.g. through a module, then this method will ignore it and return the true hostname. + * @return The full real host of the user */ virtual char* GetFullRealHost(); - /* - * Create a displayable mode string for this users umodes + /** Create a displayable mode string for this users snomasks + * @return The notice mask character sequence */ const char* FormatNoticeMasks(); + /** Process a snomask modifier string, e.g. +abc-de + * @param sm A sequence of notice mask characters + * @return True if the notice masks were successfully applied + */ bool userrec::ProcessNoticeMasks(const char *sm); + /** Returns true if a notice mask is set + * @param sm A notice mask character to check + * @return True if the notice mask is set + */ bool IsNoticeMaskSet(unsigned char sm); + /** Changed a specific notice mask value + * @param sm The server notice mask to change + * @param value An on/off value for this mask + */ void SetNoticeMask(unsigned char sm, bool value); - /* - * Create a displayable mode string for this users umodes + /** Create a displayable mode string for this users umodes + * @param The mode string */ const char* FormatModes(); + /** Returns true if a specific mode is set + * @param m The user mode + * @return True if the mode is set + */ bool IsModeSet(unsigned char m); + /** Set a specific usermode to on or off + * @param m The user mode + * @param value On or off setting of the mode + */ void SetMode(unsigned char m, bool value); /** Returns true if a user is invited to a channel. + * @param channel A channel name to look up + * @return True if the user is invited to the given channel */ virtual bool IsInvited(irc::string &channel); /** Adds a channel to a users invite list (invites them to a channel) + * @param channel A channel name to add */ virtual void InviteTo(irc::string &channel); /** Removes a channel from a users invite list. * This member function is called on successfully joining an invite only channel * to which the user has previously been invited, to clear the invitation. + * @param channel The channel to remove the invite to */ virtual void RemoveInvite(irc::string &channel); /** Returns true or false for if a user can execute a privilaged oper command. * This is done by looking up their oper type from userrec::oper, then referencing * this to their oper classes and checking the commands they can execute. + * @param command A command (should be all CAPS) + * @return True if this user can execute the command */ bool HasPermission(const std::string &command); /** Calls read() to read some data for this user using their fd. + * @param buffer The buffer to read into + * @param size The size of data to read + * @return The number of bytes read, or -1 if an error occured. */ int ReadData(void* buffer, size_t size); - /** This method adds data to the buffer of the user. + /** This method adds data to the read buffer of the user. * The buffer can grow to any size within limits of the available memory, * managed by the size of a std::string, however if any individual line in * the buffer grows over 600 bytes in length (which is 88 chars over the * RFC-specified limit per line) then the method will return false and the * text will not be inserted. + * @param a The string to add to the users read buffer + * @return True if the string was successfully added to the read buffer */ bool AddBuffer(const std::string &a); /** This method returns true if the buffer contains at least one carriage return * character (e.g. one complete line may be read) + * @return True if there is at least one complete line in the users buffer */ bool BufferIsReady(); @@ -387,6 +441,7 @@ class userrec : public connection * multiple lines if they are available. The results of this function if there * are no lines to be read are unknown, always use BufferIsReady() to check if * it is ok to read the buffer before calling GetBuffer(). + * @return The string at the tail end of this users buffer */ std::string GetBuffer(); @@ -394,11 +449,13 @@ class userrec : public connection * of a client may occur at an inopportune time such as half way through /LIST output. * The WriteErrors of clients are checked at a more ideal time (in the mainloop) and * errored clients purged. + * @param error The error string to set. */ void SetWriteError(const std::string &error); /** Returns the write error which last occured on this connection or an empty string * if none occured. + * @return The error string which has occured for this user */ const char* GetWriteError(); @@ -406,6 +463,7 @@ class userrec : public connection * You may add any amount of text up to this users sendq value, if you exceed the * sendq value, SetWriteError() will be called to set the users error string to * "SendQ exceeded", and further buffer adds will be dropped. + * @param data The data to add to the write buffer */ void AddWriteBuf(const std::string &data); @@ -418,16 +476,19 @@ class userrec : public connection void FlushWriteBuf(); /** Returns the list of channels this user has been invited to but has not yet joined. + * @return A list of channels the user is invited to */ InvitedList* GetInviteList(); /** Creates a wildcard host. * Takes a buffer to use and fills the given buffer with the host in the format *!*@hostname + * @return The wildcarded hostname in *!*@host form */ char* MakeWildHost(); /** Creates a host. * Takes a buffer to use and fills the given buffer with the host in the format nick!user@host + * @param Buffer to fill with host information */ void MakeHost(char* nhost); @@ -436,22 +497,64 @@ class userrec : public connection void CloseSocket(); /** Disconnect a user gracefully + * @param user The user to remove + * @param r The quit reason */ static void QuitUser(userrec *user, const std::string &r); + /** Add the user to WHOWAS system + */ void AddToWhoWas(); + /** Oper up the user using the given opertype. + * This will also give the +o usermode. + * @param opertype The oper type to oper as + */ void Oper(const std::string &opertype); + /** Use this method to fully connect a user. + * This will send the message of the day, check G/K/E lines, etc. + * @param Goners If the user is disconnected by this method call, the + * value of 'this' will be pushed onto this CullList. This is used by + * the core to connect many users in rapid succession without invalidating + * iterators. + */ void FullConnect(CullList* Goners); + + /** Change this users hash key to a new string. + * You should not call this function directly. It is used by the core + * to update the users hash entry on a nickchange. + * @param New new user_hash key + * @return Pointer to userrec in hash (usually 'this') + */ userrec* UpdateNickHash(const char* New); + + /** Force a nickname change. + * If the nickname change fails (for example, because the nick in question + * already exists) this function will return false, and you must then either + * output an error message, or quit the user for nickname collision. + * @param newnick The nickname to change to + * @return True if the nickchange was successful. + */ bool ForceNickChange(const char* newnick); + /** Add a client to the system. + * This will create a new userrec, insert it into the user_hash, + * initialize it as not yet registered, and add it to the socket engine. + */ static void AddClient(int socket, int port, bool iscached, insp_inaddr ip); + /** Oper down. + * This will clear the +o usermode and unset the user's oper type + */ void UnOper(); + /** Return the number of global clones of this user + */ long GlobalCloneCount(); + + /** Return the number of local clones of this user + */ long LocalCloneCount(); /** Default destructor @@ -459,31 +562,56 @@ class userrec : public connection virtual ~userrec(); }; -/** Used to hold WHOWAS information - */ namespace irc { + /** Holds whowas related functions and classes + */ namespace whowas { + /** Used to hold WHOWAS information + */ class WhoWasGroup : public classbase { public: + /** Real host + */ char* host; + /** Displayed host + */ char* dhost; + /** Ident + */ char* ident; + /** Server name + */ const char* server; + /** Fullname (GECOS) + */ char* gecos; + /** Signon time + */ time_t signon; + /** Initialize this WhoQasFroup with a user + */ WhoWasGroup(userrec* user); + /** Destructor + */ ~WhoWasGroup(); }; - + + /** A group of users related by nickname + */ typedef std::deque whowas_set; + + /** Sets of users in the whowas system + */ typedef std::map whowas_users; - + + /** Called every hour by the core to remove expired entries + */ void MaintainWhoWas(time_t TIME); }; };