From 2cb07e3b5c3b7509cbc2d296597460466fb53818 Mon Sep 17 00:00:00 2001 From: fishwaldo <> Date: Thu, 26 Dec 2002 15:15:04 +0000 Subject: [PATCH] doco updates of internal functions... see fish.dynam.ac/neo for sample --- ChangeLog | 4 +- chans.c | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- conf.c | 102 +++++++++++++++++++++++++++++++---------- dns.c | 50 ++++++++++---------- 4 files changed, 239 insertions(+), 50 deletions(-) diff --git a/ChangeLog b/ChangeLog index 0a1630b9..03a0795d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,5 @@ NeoStats ChangeLog - Anything we add/remove/fix/change is in here (even our rants) -* NeoStats * Fish & Shmad * Version ???? +* NeoStats * Fish & Shmad * Version 2.5.0 Final? - Added support to makeconf for WALLOP_INTERVAL (S) - Fixed up --enable-auth==TYPE typo in configure script - Moved to AutoConf2.13 to fix bsd ./configure issues @@ -11,6 +11,8 @@ NeoStats ChangeLog - Anything we add/remove/fix/change is in here (even our rant - Fix a adns compile error and remove the warnings - -Wall is only set when compiling with debug mode support. No need for the make.log file anymore - ./configure --enable-bignet support for more than 2000 users + - Started Documenting internal functions for DoxyGen (About time I did this) + - Created 2.6.0 branch in CVS * NeoStats * Shmad & Fish * Version 2.5.0-Release Candidate 2 - Misc. Updates (S) diff --git a/chans.c b/chans.c index ecd3d555..8a6618d0 100644 --- a/chans.c +++ b/chans.c @@ -19,7 +19,7 @@ ** USA ** ** NeoStats CVS Identification -** $Id: chans.c,v 1.36 2002/12/14 09:58:37 fishwaldo Exp $ +** $Id: chans.c,v 1.37 2002/12/26 15:15:04 fishwaldo Exp $ */ #include @@ -28,15 +28,31 @@ #include "dl.h" #include "hash.h" +/** @brief initilize the channel data + * + * Initilizes the channel data and channel hash ch. + * + * @return Nothing +*/ void init_chan_hash() { ch = hash_create(C_TABLE_SIZE, 0, 0); - if (usr_mds); - } +/** @brief Process a Topic Change + * + * Processes a Channel topic Change for particular channel and updates internals + * Also triggers off a TOPICCHANGE event for modules + * + * @param owner Char of who changed the topic. Can't be a userstruct as the user might not be online anymore + * @param c Channel Struct of channel who's topic is being changed + * @param time when the topic was changed (might have been in the past + * @param topic the new topic + * + * @return Nothing +*/ extern void Change_Topic(char *owner, Chans *c, time_t time, char *topic) { char **av; @@ -50,6 +66,15 @@ extern void Change_Topic(char *owner, Chans *c, time_t time, char *topic) { Module_Event("TOPICCHANGE",av, ac); FreeList(av, ac); } +/** @brief Compare channel modes from the channel hash + * + * used in ChanMode to compare modes (list_find argument) + * + * @param v actually its a ModeParm struct + * @param mode is the mode as a long + * + * @return 0 on match, 1 otherwise. +*/ int comparemode(const void *v, const void *mode) { ModesParm *m = (void *)v; @@ -60,6 +85,16 @@ int comparemode(const void *v, const void *mode) { } } +/** @brief Process a mode change on a channel + * + * process a mode change on a channel adding and deleting modes as required + * + * @param origin usually the server that sent the mode change. Not used + * @param av array of variables to pass + * @param ac number of variables n av + * + * @return 0 on error, number of modes processed on success. +*/ int ChanMode(char *origin, char **av, int ac) { char *modes; @@ -163,6 +198,18 @@ return j; } +/** @brief Process a mode change that affects a user on a channel + * + * process a mode change on a channel that affects a user + * + * @param c Channel Struct of channel mode being changed + * @param u User struct of user that mode is affecting + * @param add 1 means add, 0 means remove mode + * @param mode is the long int of the mode + * + * @return Nothing +*/ + void ChangeChanUserMode(Chans *c, User *u, int add, long mode) { lnode_t *cmn; Chanmem *cm; @@ -188,6 +235,17 @@ void ChangeChanUserMode(Chans *c, User *u, int add, long mode) { cm->flags &= ~mode; } } + +/** @brief Create a new channel record + * + * And insert it into the hash, mallocing required memory for it and so on + * also check that the channel hash is not full + * + * @param chan name of the channel to create + * + * @returns c the newly created channel record + * @todo Dynamically resizable channel hashes +*/ Chans *new_chan(char *chan) { Chans *c; hnode_t *cn; @@ -203,6 +261,16 @@ Chans *new_chan(char *chan) { } return c; } + +/** @brief Deletes a channel record + * + * frees any memory associated with the record and removes it from the channel hash + * + * @param c the corrosponding channel structure you wish to delete + * + * @returns Nothing +*/ + void del_chan(Chans *c) { hnode_t *cn; lnode_t *cm; @@ -229,6 +297,18 @@ void del_chan(Chans *c) { } } +/** @brief Parts a user from a channel + * + * Parts a user from a channel and raises events if required + * Events raised are PARTCHAN and DELCHAN + * if its one of our bots, also update bot channel lists + * + * @param u the User structure corrosponding to the user that left the channel + * @param chan the channel to part them from + * + * @returns Nothing +*/ + void part_chan(User *u, char *chan) { Chans *c; @@ -296,6 +376,18 @@ void part_chan(User *u, char *chan) { } } +/** @brief Change channel records when a nick change occurs + * + * goes through the channel members list, changing users nicks after a nickname change occurs + * + * @param c the channel to check (as called by the user functions) + * @param newnick the New Nickname of the client + * @param oldnick the old nickname of the client + * + * @returns Nothing + * @todo What happens if one of our bots change their nick? +*/ + void change_user_nick(Chans *c, char *newnick, char *oldnick) { lnode_t *cm; Chanmem *cml; @@ -320,6 +412,18 @@ void change_user_nick(Chans *c, char *newnick, char *oldnick) { +/** @brief Process a user joining a channel + * + * joins a user to a channel and raises JOINCHAN event and if required NEWCHAN events + * if the channel is new, a new channel record is requested and defaults are set + * if its one of our bots, also update the botchanlist + * + * @param u The User structure of the user joining the channel + * @param chan the channel name + * + * @returns Nothing +*/ + void join_chan(User *u, char *chan) { Chans *c; @@ -390,6 +494,18 @@ void join_chan(User *u, char *chan) { } } + +/** @brief Dump Channel information + * + * dump either the entire channel list, or a single channel detail. Used for debugging + * sends the output to the services channel + * + * @param chan the channel name to dump, or NULL for all channels + * + * @returns Nothing +*/ + + void chandump(char *chan) { hnode_t *cn; lnode_t *cmn; @@ -478,6 +594,17 @@ void chandump(char *chan) { } } + +/** @brief Find a channel + * + * Finds the channel structure for the channel named chan, or NULL if it can't be found + * + * @param chan the channel name to find + * + * @returns The Channel structure for chan, or NULL if it can't be found. +*/ + + Chans *findchan(char *chan) { Chans *c; hnode_t *cn; diff --git a/conf.c b/conf.c index 7714e9a7..a6fb325d 100644 --- a/conf.c +++ b/conf.c @@ -20,7 +20,7 @@ ** USA ** ** NeoStats CVS Identification -** $Id: conf.c,v 1.16 2002/10/20 16:44:33 shmad Exp $ +** $Id: conf.c,v 1.17 2002/12/26 15:15:04 fishwaldo Exp $ */ #include "stats.h" @@ -44,17 +44,30 @@ static config_option options[] = { "NEOSTAT_HOST", ARG_STR, cb_Server, 7}, { "NEOSTAT_USER", ARG_STR, cb_Server, 8}, { "WANT_PRIVMSG", ARG_STR, cb_Server, 9}, -{ "SERVICES_CHAN", ARG_STR, cb_Server, 10}, { "LOAD_MODULE", ARG_STR, cb_Module, 0}, { "ONLY_OPERS", ARG_STR, cb_Server, 11}, { "NO_LOAD", ARG_STR, cb_Server, 12} }; +/** @brief Initilize the configuration parser + * + * Currently does nothing + * + * @return Nothing + */ + void init_conf() { - if (usr_mds); } +/** @brief strip newlines carriage returns + * + * removes newlines and carriage returns from a string + * + * @param line the line to strip (warning, Modfied!) + * @retval line the stripped line + */ + void strip(char *line) { char *c; @@ -62,29 +75,46 @@ void strip(char *line) if ((c = strchr(line, '\r'))) *c = '\0'; } + +/** @brief Load the Config file + * + * Parses the Configuration File and optionally loads the external authentication libary + * + * @returns Nothing + */ + + void ConfLoad() { -/* Read in the Config File */ -printf("Reading the Config File. Please wait.....\n"); -if (!config_read("neostats.cfg", options) == 0 ) { - printf("***************************************************\n"); - printf("* Error! *\n"); - printf("* *\n"); - printf("* Config File not found, or Unable to Open *\n"); - printf("* Please check its Location, and try again *\n"); - printf("* *\n"); - printf("* NeoStats NOT Started *\n"); - printf("***************************************************\n"); - exit(0); -} -printf("Sucessfully Loaded Config File, Now Booting NeoStats\n"); -#ifdef EXTAUTH - load_module("extauth", NULL); -#endif - -done_mods = 0; + /* Read in the Config File */ + printf("Reading the Config File. Please wait.....\n"); + if (!config_read("neostats.cfg", options) == 0 ) { + printf("***************************************************\n"); + printf("* Error! *\n"); + printf("* *\n"); + printf("* Config File not found, or Unable to Open *\n"); + printf("* Please check its Location, and try again *\n"); + printf("* *\n"); + printf("* NeoStats NOT Started *\n"); + printf("***************************************************\n"); + exit(0); + } + printf("Sucessfully Loaded Config File, Now Booting NeoStats\n"); + #ifdef EXTAUTH + load_module("extauth", NULL); + #endif + done_mods = 0; } +/** @brief prepare Modules defined in the config file + * + * When the config file encounters directives to Load Modules, it calls this function which prepares to load the modules (but doesn't actually load them) + * + * @param arg the module name in this case + * @param configtype a index of what config item is currently being processed. Ignored + * @returns Nothing + */ + void cb_Module(char *arg, int configtype) { int i; strcpy(segv_location, "cb_Module"); @@ -97,6 +127,14 @@ void cb_Module(char *arg, int configtype) { log("Added Module %d :%s", i, load_mods[i]); } +/** @brief Load the modules + * + * Actually load the modules that were found in the config file + * + * @returns 1 on success, -1 when a module failed to load + * @bugs if a single module fails to load, it stops trying to load any other modules + */ + int init_modules() { int i; int rval; @@ -115,8 +153,18 @@ int init_modules() { return -1; } } -return 1; + return 1; } + + +/** @brief Process config file items + * + * Processes the config file and sets up the variables. No Error Checking is performed :( + * + * @param arg the variable value as a string + * @param configtype the index of the variable being called now + * @returns Nothing + */ void cb_Server(char *arg, int configtype) { if (configtype == 0) { @@ -158,6 +206,14 @@ void cb_Server(char *arg, int configtype) { } + +/** @brief Rehash Function + * + * Called when we recieve a rehash signal. Does nothing atm + * + * @returns Nothing + */ + void rehash() { /* nothing, yet */ diff --git a/dns.c b/dns.c index e1534a73..4793a288 100644 --- a/dns.c +++ b/dns.c @@ -20,7 +20,7 @@ ** USA ** ** NeoStats CVS Identification -** $Id: dns.c,v 1.8 2002/12/26 14:15:07 fishwaldo Exp $ +** $Id: dns.c,v 1.9 2002/12/26 15:15:04 fishwaldo Exp $ */ @@ -34,15 +34,25 @@ #include "stats.h" #include + + +/** @brief DNS lookup Struct + * structure containing all pending DNS lookups and the callback functions + */ struct dnslookup_struct { - adns_query q; - adns_answer *a; - char data[255]; - void (*callback)(char *data, adns_answer *a); + adns_query q; /**< the ADNS query */ + adns_answer *a; /**< the ADNS result if we have completed */ + char data[255]; /**< the User data based to the callback */ + void (*callback)(char *data, adns_answer *a); /**< a function pointer to call when we have a result */ }; +/** @brief DNS structures + */ typedef struct dnslookup_struct DnsLookup; +/** @brief List of DNS queryies + * Contains DnsLookup entries + */ list_t *dnslist; @@ -104,14 +114,11 @@ int dns_lookup(char *str, adns_rrtype type, void (*callback)(char *data, adns_a } -/* init_dns -** inputs - Nothing -** -** outputs - integer saying if the dns init was successfull (1 = yes, 0 = no) -** -** side effects - Initilizes the dns lookup list_t -** -** use this function to initilize the dns functions +/** @brief sets up DNS subsystem + * + * configures ADNS for use with NeoStats. + * + * @return returns 1 on success, 0 on failure */ int init_dns() { @@ -135,16 +142,13 @@ int init_dns() { } -/* do_dns -** inputs - Nothing -** -** outputs - Nothing -** -** side effects - Goes through the dnslist of pending queries and calls the callback function for each lookup -** with the adns_answer set. Always calls the callback function even if the lookup was unsuccessfull -** its upto the callback function to make check the answer struct to see if it failed or not -** -** This function is called each loop. +/** @brief Checks for Completed DNS queries + * + * Goes through the dnslist of pending queries and calls the callback function for each lookup + * with the adns_answer set. Always calls the callback function even if the lookup was unsuccessfull +* its upto the callback function to make check the answer struct to see if it failed or not + * + * @return Nothing */ void do_dns() {