From: Michael Poole Date: Sun, 3 Oct 2004 14:12:35 +0000 (+0000) Subject: Doxyfy jupe.h and jupe.c. X-Git-Url: http://git.pk910.de/?a=commitdiff_plain;h=a312302f6ea15125ce0a263c01d04e4762f2a102;p=ircu2.10.12-pk.git Doxyfy jupe.h and jupe.c. git-svn-id: file:///home/klmitch/undernet-ircu/undernet-ircu-svn/ircu2/trunk@1208 c9e4aea6-c8fd-4c43-8297-357d70d61c8c --- diff --git a/include/jupe.h b/include/jupe.h index 795d33b..47da2ed 100644 --- a/include/jupe.h +++ b/include/jupe.h @@ -19,8 +19,10 @@ * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - * - * $Id$ + */ +/** @file + * @brief Interface and declarations for juped server handling. + * @version $Id$ */ #ifndef INCLUDED_sys_types_h #include @@ -30,31 +32,40 @@ struct Client; -#define JUPE_MAX_EXPIRE 604800 /* max expire: 7 days */ +#define JUPE_MAX_EXPIRE 604800 /**< Maximum jupe expiration time (7 days). */ +/** Describes a juped server. + * A hub will not accept new connections from a juped server. + */ struct Jupe { - struct Jupe* ju_next; - struct Jupe** ju_prev_p; - char* ju_server; - char* ju_reason; - time_t ju_expire; - time_t ju_lastmod; - unsigned int ju_flags; + struct Jupe* ju_next; /**< Pointer to next Jupe. */ + struct Jupe** ju_prev_p; /**< Pointer to previous next pointer. */ + char* ju_server; /**< Name of server to jupe. */ + char* ju_reason; /**< Reason for the jupe. */ + time_t ju_expire; /**< Expiration time of the jupe. */ + time_t ju_lastmod; /**< Last modification time (if any) for the jupe. */ + unsigned int ju_flags; /**< Status flags for the jupe. */ }; -#define JUPE_ACTIVE 0x0001 -#define JUPE_LOCAL 0x0002 -#define JUPE_LDEACT 0x0004 /* locally deactivated */ +#define JUPE_ACTIVE 0x0001 /**< Jupe is globally active. */ +#define JUPE_LOCAL 0x0002 /**< Jupe only applies to this server. */ +#define JUPE_LDEACT 0x0004 /**< Jupe is locally deactivated */ #define JUPE_MASK (JUPE_ACTIVE | JUPE_LOCAL) #define JUPE_ACTMASK (JUPE_ACTIVE | JUPE_LDEACT) +/** Test whether \a j is active. */ #define JupeIsActive(j) (((j)->ju_flags & JUPE_ACTMASK) == JUPE_ACTIVE) +/** Test whether \a j is globally (remotely) active. */ #define JupeIsRemActive(j) ((j)->ju_flags & JUPE_ACTIVE) +/** Test whether \a j is local. */ #define JupeIsLocal(j) ((j)->ju_flags & JUPE_LOCAL) +/** Get the server name for \a j. */ #define JupeServer(j) ((j)->ju_server) +/** Get the reason fro \a j. */ #define JupeReason(j) ((j)->ju_reason) +/** Get the last modification time for \a j. */ #define JupeLastMod(j) ((j)->ju_lastmod) extern int jupe_add(struct Client *cptr, struct Client *sptr, char *server, diff --git a/ircd/jupe.c b/ircd/jupe.c index 7597ab6..3d69a74 100644 --- a/ircd/jupe.c +++ b/ircd/jupe.c @@ -17,8 +17,10 @@ * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - * - * $Id$ + */ +/** @file + * @brief Implementation of juped server handling functions. + * @version $Id$ */ #include "config.h" @@ -44,8 +46,16 @@ #include #include +/** List of jupes. */ static struct Jupe *GlobalJupeList = 0; +/** Allocate a new jupe with the given parameters. + * @param[in] server Server name to jupe. + * @param[in] reason Reason for jupe. + * @param[in] expire Expiration time for jupe. + * @param[in] lastmod Last modification time for jupe. + * @param[in] flags Flags to set for the jupe. + */ static struct Jupe * make_jupe(char *server, char *reason, time_t expire, time_t lastmod, unsigned int flags) @@ -70,6 +80,11 @@ make_jupe(char *server, char *reason, time_t expire, time_t lastmod, return ajupe; } +/** Apply a jupe. + * @param[in] cptr Local client that sent us the jupe. + * @param[in] sptr Originator of the jupe. + * @param[in] jupe Jupe to check. + */ static int do_jupe(struct Client *cptr, struct Client *sptr, struct Jupe *jupe) { @@ -87,6 +102,11 @@ do_jupe(struct Client *cptr, struct Client *sptr, struct Jupe *jupe) return exit_client_msg(cptr, acptr, &me, "Juped: %s", jupe->ju_reason); } +/** Forward a jupe to another server. + * @param[in] cptr Local client that sent us the jupe. + * @param[in] sptr Originator of the jupe. + * @param[in] jupe Jupe to forward. + */ static void propagate_jupe(struct Client *cptr, struct Client *sptr, struct Jupe *jupe) { @@ -99,6 +119,17 @@ propagate_jupe(struct Client *cptr, struct Client *sptr, struct Jupe *jupe) jupe->ju_reason); } +/** Add a new server jupe. + * @param[in] cptr Local client that sent us the jupe. + * @param[in] sptr Originator of the jupe. + * @param[in] server Server name to jupe. + * @param[in] reason Reason for the jupe. + * @param[in] expire Jupe duration in seconds. + * @param[in] lastmod Last modification timestamp (or NULL). + * @param[in] flags Flags to set on jupe. + * @return Zero, unless the jupe causes \a cptr to be SQUIT, in which + * case CPTR_KILLED. + */ int jupe_add(struct Client *cptr, struct Client *sptr, char *server, char *reason, time_t expire, time_t lastmod, unsigned int flags) @@ -142,6 +173,15 @@ jupe_add(struct Client *cptr, struct Client *sptr, char *server, char *reason, return do_jupe(cptr, sptr, ajupe); /* remove server if necessary */ } +/** Activate a jupe, optionally changing its lastmod and flags. + * @param[in] cptr Local client that sent us the jupe. + * @param[in] sptr Originator of the jupe. + * @param[in] jupe Jupe to activate. + * @param[in] lastmod New timestamp for last modification of the jupe. + * @param[in] flags Flags to set on the jupe. + * @return Zero, unless the jupe causes \a cptr to be SQUIT, in which + * case CPTR_KILLED. + */ int jupe_activate(struct Client *cptr, struct Client *sptr, struct Jupe *jupe, time_t lastmod, unsigned int flags) @@ -185,6 +225,14 @@ jupe_activate(struct Client *cptr, struct Client *sptr, struct Jupe *jupe, return do_jupe(cptr, sptr, jupe); } +/** Deactivate a jupe. + * @param[in] cptr Local client that sent us the jupe. + * @param[in] sptr Originator of the jupe. + * @param[in] jupe Jupe to deactivate. + * @param[in] lastmod New timestamp for last modification of the jupe. + * @param[in] flags Flags to set on the jupe. + * @return Zero. + */ int jupe_deactivate(struct Client *cptr, struct Client *sptr, struct Jupe *jupe, time_t lastmod, unsigned int flags) @@ -234,6 +282,10 @@ jupe_deactivate(struct Client *cptr, struct Client *sptr, struct Jupe *jupe, return 0; } +/** Find a jupe by name. + * @param[in] server %Jupe name to search for. + * @return Matching jupe (or NULL if none match). + */ struct Jupe * jupe_find(char *server) { @@ -252,6 +304,9 @@ jupe_find(char *server) return 0; } +/** Unlink and free an unused jupe. + * @param[in] jupe Server jupe to free. + */ void jupe_free(struct Jupe* jupe) { @@ -266,6 +321,9 @@ jupe_free(struct Jupe* jupe) MyFree(jupe); } +/** Send the full list of active global jupes to \a cptr. + * @param[in] cptr Local server to send jupes to. + */ void jupe_burst(struct Client *cptr) { @@ -285,6 +343,10 @@ jupe_burst(struct Client *cptr) } } +/** Forward a jupe to another server. + * @param[in] cptr %Server to send jupe to. + * @param[in] jupe Jupe to forward. + */ int jupe_resend(struct Client *cptr, struct Jupe *jupe) { @@ -299,6 +361,11 @@ jupe_resend(struct Client *cptr, struct Jupe *jupe) return 0; } +/** Send a jupe (or a list of jupes) to a server. + * @param[in] sptr Client searching for jupes. + * @param[in] server Name of jupe to search for (if NULL, list all). + * @return Zero. + */ int jupe_list(struct Client *sptr, char *server) { @@ -331,6 +398,10 @@ jupe_list(struct Client *sptr, char *server) return send_reply(sptr, RPL_ENDOFJUPELIST); } +/** Count jupes and memory used by them. + * @param[out] ju_size Receives total number of bytes allocated for jupes. + * @return Number of jupes currently allocated. + */ int jupe_memory_count(size_t *ju_size) {