diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/base.h | 19 | ||||
| -rw-r--r-- | include/channels.h | 19 | ||||
| -rw-r--r-- | include/connection.h | 37 |
3 files changed, 70 insertions, 5 deletions
diff --git a/include/base.h b/include/base.h index c959cf869..d253c5dc3 100644 --- a/include/base.h +++ b/include/base.h @@ -56,23 +56,34 @@ class Extensible : public classbase public: /** Extend an Extensible class. + * + * @param key The key parameter is an arbitary string which identifies the extension data + * @param p This parameter is a pointer to any data you wish to associate with the object + * * You must provide a key to store the data as, and a void* to the data (typedef VoidPointer) * The data will be inserted into the map. If the data already exists, you may not insert it * twice, Extensible::Extend will return false in this case. - * On successful extension, Extend returns true. + * + * @return Returns true on success, false if otherwise */ bool Extend(std::string key, char* p); /** Shrink an Extensible class. + * + * @param key The key parameter is an arbitary string which identifies the extension data + * * You must provide a key name. The given key name will be removed from the classes data. If * you provide a nonexistent key (case is important) then the function will return false. - * Returns true on success. + * + * @return Returns true on success. */ bool Shrink(std::string key); /** Get an extension item. - * You must provide a key name, which is case sensitive. If you provide a non-existent key name, - * the function returns NULL, otherwise a pointer to the item referenced by the key is returned. + * + * @param key The key parameter is an arbitary string which identifies the extension data + * + * @return If you provide a non-existent key name, the function returns NULL, otherwise a pointer to the item referenced by the key is returned. */ char* GetExt(std::string key); }; diff --git a/include/channels.h b/include/channels.h index 7df2d665e..ed57955a2 100644 --- a/include/channels.h +++ b/include/channels.h @@ -149,22 +149,33 @@ class chanrec : public Extensible BanList bans; /** Sets or unsets a custom mode in the channels info + * @param mode The mode character to set or unset + * @param mode_on True if you want to set the mode or false if you want to remove it */ void SetCustomMode(char mode,bool mode_on); /** Sets or unsets the parameters for a custom mode in a channels info + * @param mode The mode character to set or unset + * @param parameter The parameter string to associate with this mode character + * @param mode_on True if you want to set the mode or false if you want to remove it */ void SetCustomModeParam(char mode,char* parameter,bool mode_on); /** Returns true if a custom mode is set on a channel + * @param mode The mode character you wish to query + * @return True if the custom mode is set, false if otherwise */ bool IsCustomModeSet(char mode); /** Returns the parameter for a custom mode on a channel. + * @param mode The mode character you wish to query + * * For example if "+L #foo" is set, and you pass this method * 'L', it will return '#foo'. If the mode is not set on the * channel, or the mode has no parameters associated with it, * it will return an empty string. + * + * @return The parameter for this mode is returned, or an empty string */ std::string GetModeParameter(char mode); @@ -172,10 +183,14 @@ class chanrec : public Extensible * This returns the channel reference counter, which is initialized * to 0 when the channel is created and incremented/decremented * upon joins, parts quits and kicks. + * + * @return The number of users on this channel */ long GetUserCounter(); /** Add a user pointer to the internal reference list + * @param castuser This should be a pointer to a userrec, casted to char* + * * The data inserted into the reference list is a table as it is * an arbitary pointer compared to other users by its memory address, * as this is a very fast 32 or 64 bit integer comparison. @@ -183,6 +198,8 @@ class chanrec : public Extensible void AddUser(char* castuser); /** Delete a user pointer to the internal reference list + * @param castuser This should be a pointer to a userrec, casted to char* + * * The data removed from the reference list is a table as it is * an arbitary pointer compared to other users by its memory address, * as this is a very fast 32 or 64 bit integer comparison. @@ -195,6 +212,8 @@ class chanrec : public Extensible * channel membership for PRIVMSG, NOTICE, QUIT, PART etc. * The resulting pointer to the vector should be considered * readonly and only modified via AddUser and DelUser. + * + * @return This function returns a vector of userrec pointers, each of which has been casted to char* to prevent circular references */ std::vector<char*> *GetUsers(); diff --git a/include/connection.h b/include/connection.h index 88dc3ea54..2d473bde4 100644 --- a/include/connection.h +++ b/include/connection.h @@ -141,34 +141,42 @@ class ircd_connector : public Extensible std::string GetServerName(); /** Set the server name of this connection + * @param serv The server name to set */ void SetServerName(std::string serv); /** Get the file descriptor associated with this connection + * @return The file descriptor associated with this connection */ int GetDescriptor(); /** Set the file descriptor for this connection + * @param fd The file descriptor to associate with the connection */ void SetDescriptor(int fd); /** Get the state flags for this connection + * @return The state flags associated with this connection */ int GetState(); /** Set the state flags for this connection + * @param state The state flags to set for this connection */ void SetState(int state); /** Get the ip address (not servername) associated with this connection + * @return The connections IP address in dotted decimal form */ char* GetServerIP(); /** Get the server description of this connection + * @return The description (GECOS) of this connection */ std::string GetDescription(); /** Set the server description of this connection + * @param desc The description (GECOS) of this connection to be set */ void SetDescription(std::string desc); @@ -176,14 +184,20 @@ class ircd_connector : public Extensible * If the connection is outbound this will be the remote port * otherwise it will be the local port, so it can always be * gautanteed as open at the address given in GetServerIP(). + * + * @return The port number of this connection */ int GetServerPort(); /** Set the port used by this connection + * @param p The port number to set for this connection */ void SetServerPort(int p); /** Set both the host and the port in one operation for this connection + * @param newhost The hostname to set for this connection + * @param newport The port number to set for this connection + * @return True on success, false on failure */ bool SetHostAndPort(char* newhost, int newport); @@ -193,14 +207,20 @@ class ircd_connector : public Extensible void CloseConnection(); /** This method adds text to the ircd connection's buffer + * @param a The text to add to the buffer up to a maximum size of 1MB + * * This buffer's maximum size is one megabyte, the method returning false * if the buffer is full. + * + * @return True on success, false if the buffer is full or the connection is down */ bool AddBuffer(std::string a); /** This method returns true if the buffer contains at least one * carriage return character, e.g. one line can be read from the * buffer successfully. + * + * @return True if there is at least one complete line waiting to be processed */ bool BufferIsComplete(); @@ -211,42 +231,57 @@ class ircd_connector : public Extensible /** This method retrieves the first string from the tail end of the * buffer and advances the tail end of the buffer past the returned * string, in a similar manner to strtok(). + * + * @return The first line of the buffer up to a carriage return */ std::string GetBuffer(); /** This method sets the version string of the remote server + * @param newversion The version string to set */ void SetVersionString(std::string newversion); /** This method returns the version string of the remote server. * If the server has no version string an empty string is returned. + * + * @return The version text of this connection */ std::string GetVersionString(); - /** Adds data to the connection's sendQ to be flushed later + /** Adds data to the connection's sendQ to be flushed later. + * @param data The data to add to the write buffer + * * Fails if there is an error pending on the connection. + * + * @return True on success, false if the connection is down or the buffer is full */ bool AddWriteBuf(std::string data); /** Flushes as much of the data from the buffer as possible, * and advances the queue pointer to what is left. + * + * @return True if the flush succeeded, false if the connection is down */ bool FlushWriteBuf(); /** Sets the error string for this connection + * @param error The error string to set */ void SetWriteError(std::string error); /** Gets the error string for this connection + * @return The last error to occur or an empty string */ std::string GetWriteError(); /** Returns true if there is data to be written that hasn't been sent yet + * @return True if the buffer is not empty */ bool HasBufferedOutput(); /** Checks if the connection replied to its last ping, and if it did * sends another and returns true, if not, returns false. + * @return True if the server is still replying to pings */ bool CheckPing(); |