From c51941c2f6c70ade70091f7ed64ac55cde59478b Mon Sep 17 00:00:00 2001 From: Michael Poole Date: Wed, 29 Sep 2004 03:13:07 +0000 Subject: [PATCH] Doxyfy gline.h and gline.c. git-svn-id: file:///home/klmitch/undernet-ircu/undernet-ircu-svn/ircu2/trunk@1190 c9e4aea6-c8fd-4c43-8297-357d70d61c8c --- include/gline.h | 65 +++++++++++-------- ircd/gline.c | 161 +++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 179 insertions(+), 47 deletions(-) diff --git a/include/gline.h b/include/gline.h index f3f88eb..7576f07 100644 --- a/include/gline.h +++ b/include/gline.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 Structures and APIs for G-line manipulation. + * @version $Id$ */ #ifndef INCLUDED_sys_types_h #include @@ -34,48 +36,61 @@ struct Client; struct StatDesc; -#define GLINE_MAX_EXPIRE 604800 /* max expire: 7 days */ +#define GLINE_MAX_EXPIRE 604800 /**< max expire: 7 days */ +/** Description of a G-line. */ struct Gline { - struct Gline *gl_next; - struct Gline**gl_prev_p; - char *gl_user; - char *gl_host; - char *gl_reason; - time_t gl_expire; - time_t gl_lastmod; - struct irc_in_addr gl_addr; /* We store the IP in binary for ip glines */ - unsigned char gl_bits; - unsigned int gl_flags; + struct Gline *gl_next; /**< Next G-line in linked list. */ + struct Gline**gl_prev_p; /**< Previous pointer to this G-line. */ + char *gl_user; /**< Username mask (or channel/realname mask). */ + char *gl_host; /**< Host prtion of mask. */ + char *gl_reason; /**< Reason for G-line. */ + time_t gl_expire; /**< Expiration timestamp. */ + time_t gl_lastmod; /**< Last modification timestamp. */ + struct irc_in_addr gl_addr; /**< IP address (for IP-based G-lines). */ + unsigned char gl_bits; /**< Usable bits in gl_addr. */ + unsigned int gl_flags; /**< G-line status flags. */ }; -#define GLINE_ACTIVE 0x0001 -#define GLINE_IPMASK 0x0002 -#define GLINE_BADCHAN 0x0004 -#define GLINE_LOCAL 0x0008 -#define GLINE_ANY 0x0010 -#define GLINE_FORCE 0x0020 -#define GLINE_EXACT 0x0040 -#define GLINE_LDEACT 0x0080 /* locally deactivated */ -#define GLINE_GLOBAL 0x0100 /* find only global glines */ -#define GLINE_LASTMOD 0x0200 /* find only glines with non-zero lastmod */ -#define GLINE_OPERFORCE 0x0400 /* oper forcing gline to be set */ -#define GLINE_REALNAME 0x0800 /* gline matches only the realname field */ +#define GLINE_ACTIVE 0x0001 /**< G-line is active. */ +#define GLINE_IPMASK 0x0002 /**< gl_addr and gl_bits fields are valid. */ +#define GLINE_BADCHAN 0x0004 /**< G-line prohibits users from joining a channel. */ +#define GLINE_LOCAL 0x0008 /**< G-line only applies to this server. */ +#define GLINE_ANY 0x0010 /**< Search flag: Find any G-line. */ +#define GLINE_FORCE 0x0020 /**< Override normal limits on G-lines. */ +#define GLINE_EXACT 0x0040 /**< Exact match only (no wildcards). */ +#define GLINE_LDEACT 0x0080 /**< Locally deactivated. */ +#define GLINE_GLOBAL 0x0100 /**< Find only global G-lines. */ +#define GLINE_LASTMOD 0x0200 /**< Find only G-lines with non-zero lastmod. */ +#define GLINE_OPERFORCE 0x0400 /**< Oper forcing G-line to be set. */ +#define GLINE_REALNAME 0x0800 /**< G-line matches only the realname field. */ +/** Controllable flags that can be set on an actual G-line. */ #define GLINE_MASK (GLINE_ACTIVE | GLINE_BADCHAN | GLINE_LOCAL | GLINE_REALNAME) +/** Mask for G-line activity flags. */ #define GLINE_ACTMASK (GLINE_ACTIVE | GLINE_LDEACT) +/** Test whether \a g is active. */ #define GlineIsActive(g) (((g)->gl_flags & GLINE_ACTMASK) == \ GLINE_ACTIVE) +/** Test whether \a g is remotely (globally) active. */ #define GlineIsRemActive(g) ((g)->gl_flags & GLINE_ACTIVE) +/** Test whether \a g is an IP-based G-line. */ #define GlineIsIpMask(g) ((g)->gl_flags & GLINE_IPMASK) +/** Test whether \a g is a realname-based G-line. */ #define GlineIsRealName(g) ((g)->gl_flags & GLINE_REALNAME) +/** Test whether \a g is a BADCHAN. */ #define GlineIsBadChan(g) ((g)->gl_flags & GLINE_BADCHAN) +/** Test whether \a g is local to this server. */ #define GlineIsLocal(g) ((g)->gl_flags & GLINE_LOCAL) +/** Return user mask of a G-line. */ #define GlineUser(g) ((g)->gl_user) +/** Return host mask of a G-line. */ #define GlineHost(g) ((g)->gl_host) +/** Return reason/message of a G-line. */ #define GlineReason(g) ((g)->gl_reason) +/** Return last modification time of a G-line. */ #define GlineLastMod(g) ((g)->gl_lastmod) extern int gline_propagate(struct Client *cptr, struct Client *sptr, diff --git a/ircd/gline.c b/ircd/gline.c index 7a7cc63..a0a1eb8 100644 --- a/ircd/gline.c +++ b/ircd/gline.c @@ -5,7 +5,7 @@ * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 1, or (at your option) + * the Free Software Foundation; either version 2, or (at your option) * any later version. * * This program is distributed in the hope that it will be useful, @@ -16,8 +16,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 Gline manipulation functions. + * @version $Id$ */ #include "config.h" @@ -50,22 +52,34 @@ #include #include /* for inet_ntoa */ -#define CHECK_APPROVED 0 /* Mask is acceptable */ -#define CHECK_OVERRIDABLE 1 /* Mask is acceptable, but not by default */ -#define CHECK_REJECTED 2 /* Mask is totally unacceptable */ +#define CHECK_APPROVED 0 /**< Mask is acceptable */ +#define CHECK_OVERRIDABLE 1 /**< Mask is acceptable, but not by default */ +#define CHECK_REJECTED 2 /**< Mask is totally unacceptable */ -#define MASK_WILD_0 0x01 /* Wildcards in the last position */ -#define MASK_WILD_1 0x02 /* Wildcards in the next-to-last position */ +#define MASK_WILD_0 0x01 /**< Wildcards in the last position */ +#define MASK_WILD_1 0x02 /**< Wildcards in the next-to-last position */ -#define MASK_WILD_MASK 0x03 /* Mask out the positional wildcards */ +#define MASK_WILD_MASK 0x03 /**< Mask out the positional wildcards */ -#define MASK_WILDS 0x10 /* Mask contains wildcards */ -#define MASK_IP 0x20 /* Mask is an IP address */ -#define MASK_HALT 0x40 /* Finished processing mask */ +#define MASK_WILDS 0x10 /**< Mask contains wildcards */ +#define MASK_IP 0x20 /**< Mask is an IP address */ +#define MASK_HALT 0x40 /**< Finished processing mask */ +/** List of user G-lines. */ struct Gline* GlobalGlineList = 0; +/** List of BadChan G-lines. */ struct Gline* BadChanGlineList = 0; +/** Find canonical user and host for a string. + * If \a userhost starts with '$', assign \a userhost to *user_p and NULL to *host_p. + * Otherwise, if \a userhost contains '@', assign the earlier part of it to *user_p and the rest to *host_p. + * Otherwise, assign \a def_user to *user_p and \a userhost to *host_p. + * + * @param[in] userhost Input string from user. + * @param[out] user_p Gets pointer to user (or channel/realname) part of hostmask. + * @param[out] host_p Gets point to host part of hostmask (may be assigned NULL). + * @param[in] def_user Default value for user part. + */ static void canon_userhost(char *userhost, char **user_p, char **host_p, char *def_user) { @@ -87,6 +101,15 @@ canon_userhost(char *userhost, char **user_p, char **host_p, char *def_user) } } +/** Create a Gline structure. + * @param[in] user User part of mask. + * @param[in] host Host part of mask (NULL if not applicable). + * @param[in] reason Reason for G-line. + * @param[in] expire Expiration timestamp. + * @param[in] lastmod Last modification timestamp. + * @param[in] flags Bitwise combination of GLINE_* bits. + * @return Newly allocated G-line. + */ static struct Gline * make_gline(char *user, char *host, char *reason, time_t expire, time_t lastmod, unsigned int flags) @@ -163,12 +186,22 @@ make_gline(char *user, char *host, char *reason, time_t expire, time_t lastmod, return gline; } +/** Check local clients against a new G-line. + * If the G-line is inactive or a badchan, return immediately. + * Otherwise, if any users match it, disconnect them. + * @param[in] cptr Peer connect that sent the G-line. + * @param[in] sptr Client that originated the G-line. + * @param[in] gline New G-line to check. + * @return Zero, unless \a sptr G-lined himself, in which case CPTR_KILLED. + */ static int do_gline(struct Client *cptr, struct Client *sptr, struct Gline *gline) { struct Client *acptr; int fd, retval = 0, tval; + if (GlineIsBadChan(gline)) /* no action taken on badchan glines */ + return 0; if (!GlineIsActive(gline)) /* no action taken on inactive glines */ return 0; @@ -222,12 +255,14 @@ do_gline(struct Client *cptr, struct Client *sptr, struct Gline *gline) return retval; } -/* - * This routine implements the mask checking applied to local - * G-lines. Basically, host masks must have a minimum of two non-wild - * domain fields, and IP masks must have a minimum of 16 bits. If the - * mask has even one wild-card, OVERRIDABLE is returned, assuming the - * other check doesn't fail. +/** + * Implements the mask checking applied to local G-lines. + * Basically, host masks must have a minimum of two non-wild domain + * fields, and IP masks must have a minimum of 16 bits. If the mask + * has even one wild-card, OVERRIDABLE is returned, assuming the other + * check doesn't fail. + * @param[in] mask G-line mask to check. + * @return One of CHECK_REJECTED, CHECK_OVERRIDABLE, or CHECK_APPROVED. */ static int gline_checkmask(char *mask) @@ -292,6 +327,12 @@ gline_checkmask(char *mask) return flags & MASK_WILDS ? CHECK_OVERRIDABLE : CHECK_APPROVED; } +/** Forward a G-line to other servers. + * @param[in] cptr Client that sent us the G-line. + * @param[in] sptr Client that originated the G-line. + * @param[in] gline G-line to forward. + * @return Zero. + */ int gline_propagate(struct Client *cptr, struct Client *sptr, struct Gline *gline) { @@ -317,6 +358,22 @@ gline_propagate(struct Client *cptr, struct Client *sptr, struct Gline *gline) return 0; } +/** Create a new G-line and add it to global lists. + * \a userhost may be in one of four forms: + * \li A channel name, to add a BadChan. + * \li A string starting with $R and followed by a mask to match against their realname. + * \li A user\@IP mask (user\@ part optional) to create an IP-based ban. + * \li A user\@host mask (user\@ part optional) to create a hostname ban. + * + * @param[in] cptr Client that sent us the G-line. + * @param[in] sptr Client that originated the G-line. + * @param[in] userhost Text mask for the G-line. + * @param[in] reason Reason for G-line. + * @param[in] expire Duration of G-line in seconds. + * @param[in] lastmod Last modification time of G-line. + * @param[in] flags Bitwise combination of GLINE_* flags. + * @return Zero or CPTR_KILLED, depending on whether \a sptr is suicidal. + */ int gline_add(struct Client *cptr, struct Client *sptr, char *userhost, char *reason, time_t expire, time_t lastmod, unsigned int flags) @@ -412,12 +469,17 @@ gline_add(struct Client *cptr, struct Client *sptr, char *userhost, gline_propagate(cptr, sptr, agline); - if (GlineIsBadChan(agline)) - return 0; - return do_gline(cptr, sptr, agline); /* knock off users if necessary */ } +/** Activate a currently inactive G-line. + * @param[in] cptr Peer that told us to activate the G-line. + * @param[in] sptr Client that originally thought it was a good idea. + * @param[in] gline G-line to activate. + * @param[in] lastmod New value for last modification timestamp. + * @param[in] flags 0 if the activation should be propagated, GLINE_LOCAL if not. + * @return Zero, unless \a sptr had a death wish (in which case CPTR_KILLED). + */ int gline_activate(struct Client *cptr, struct Client *sptr, struct Gline *gline, time_t lastmod, unsigned int flags) @@ -465,9 +527,17 @@ gline_activate(struct Client *cptr, struct Client *sptr, struct Gline *gline, if (!(flags & GLINE_LOCAL)) /* don't propagate local changes */ gline_propagate(cptr, sptr, gline); - return GlineIsBadChan(gline) ? 0 : do_gline(cptr, sptr, gline); + return do_gline(cptr, sptr, gline); } +/** Deactivate a G-line. + * @param[in] cptr Peer that gave us the message. + * @param[in] sptr Client that initiated the deactivation. + * @param[in] gline G-line to deactivate. + * @param[in] lastmod New value for G-line last modification timestamp. + * @param[in] flags GLINE_LOCAL to only deactivate locally, 0 to propagate. + * @return Zero. + */ int gline_deactivate(struct Client *cptr, struct Client *sptr, struct Gline *gline, time_t lastmod, unsigned int flags) @@ -532,6 +602,20 @@ gline_deactivate(struct Client *cptr, struct Client *sptr, struct Gline *gline, return 0; } +/** Find a G-line for a particular mask, guided by certain flags. + * Certain bits in \a flags are interpreted specially: + *
+ *
GLINE_ANY
Search both BadChans and user G-lines.
+ *
GLINE_BADCHAN
Search BadChans.
+ *
GLINE_GLOBAL
Only match global G-lines.
+ *
GLINE_LASTMOD
Only match G-lines with a last modification time.
+ *
GLINE_EXACT
Require an exact match of G-line mask.
+ *
anything else
Search user G-lines.
+ *
+ * @param[in] userhost Mask to search for. + * @param[in] flags Bitwise combination of GLINE_* flags. + * @return First matching G-line, or NULL if none are found. + */ struct Gline * gline_find(char *userhost, unsigned int flags) { @@ -592,6 +676,12 @@ gline_find(char *userhost, unsigned int flags) return gline; } +/** Find a matching G-line for a user. + * @param[in] cptr Client to compare against. + * @param[in] flags Bitwise combination of GLINE_GLOBAL and/or + * GLINE_LASTMOD to limit matches. + * @return Matching G-line, or NULL if none are found. + */ struct Gline * gline_lookup(struct Client *cptr, unsigned int flags) { @@ -644,6 +734,9 @@ gline_lookup(struct Client *cptr, unsigned int flags) return 0; } +/** Delink and free a G-line. + * @param[in] gline G-line to free. + */ void gline_free(struct Gline *gline) { @@ -660,6 +753,9 @@ gline_free(struct Gline *gline) MyFree(gline); } +/** Burst all known global G-lines to another server. + * @param[in] cptr Destination of burst. + */ void gline_burst(struct Client *cptr) { @@ -693,6 +789,11 @@ gline_burst(struct Client *cptr) } } +/** Send a G-line to another server. + * @param[in] cptr Who to inform of the G-line. + * @param[in] gline G-line to send. + * @return Zero. + */ int gline_resend(struct Client *cptr, struct Gline *gline) { @@ -709,6 +810,13 @@ gline_resend(struct Client *cptr, struct Gline *gline) return 0; } +/** Display one or all G-lines to a user. + * If \a userhost is not NULL, only send the first matching G-line. + * Otherwise send the whole list. + * @param[in] sptr User asking for G-line list. + * @param[in] userhost G-line mask to search for (or NULL). + * @return Zero. + */ int gline_list(struct Client *sptr, char *userhost) { @@ -758,6 +866,11 @@ gline_list(struct Client *sptr, char *userhost) return send_reply(sptr, RPL_ENDOFGLIST); } +/** Statistics callback to list G-lines. + * @param[in] sptr Client requesting statistics. + * @param[in] sd Stats descriptor for request (ignored). + * @param[in] param Extra parameter from user (ignored). + */ void gline_stats(struct Client *sptr, const struct StatDesc *sd, char *param) @@ -778,6 +891,10 @@ gline_stats(struct Client *sptr, const struct StatDesc *sd, } } +/** Calculate memory used by G-lines. + * @param[out] gl_size Number of bytes used by G-lines. + * @return Number of G-lines in use. + */ int gline_memory_count(size_t *gl_size) { -- 2.20.1