lists.{c|h}: code cleanup; more documentation
authorAlexander Barton <alex@barton.de>
Sun, 25 Dec 2011 13:48:13 +0000 (14:48 +0100)
committerAlexander Barton <alex@barton.de>
Sun, 25 Dec 2011 13:48:13 +0000 (14:48 +0100)
src/ngircd/lists.c
src/ngircd/lists.h

index 9a10ac7dab9f50995b3107b0f1b136cae92f9c44..8e120bfeb16a059bf17d043dd440bd69c587cfe7 100644 (file)
 #define MASK_LEN       (2*CLIENT_HOST_LEN)
 
 struct list_elem {
-       struct list_elem *next;
-       char mask[MASK_LEN];
-       char *reason;
+       struct list_elem *next; /** pointer to next list element */
+       char mask[MASK_LEN];    /** IRC mask */
+       char *reason;           /** Optional "reason" text */
        time_t valid_until;     /** 0: unlimited; 1: once; t(>1): until t */
 };
 
-
+/**
+ * Get IRC mask stored in list element.
+ *
+ * @param list_elem List element.
+ * @return Pointer to IRC mask
+ */
 GLOBAL const char *
 Lists_GetMask(const struct list_elem *e)
 {
+       assert(e != NULL);
        return e->mask;
 }
 
+/**
+ * Get optional "reason" text stored in list element.
+ *
+ * @param list_elem List element.
+ * @return Pointer to "reason" text or NULL.
+ */
 GLOBAL const char *
 Lists_GetReason(const struct list_elem *e)
 {
@@ -57,6 +69,12 @@ Lists_GetReason(const struct list_elem *e)
        return e->reason;
 }
 
+/**
+ * Get "validity" value stored in list element.
+ *
+ * @param list_elem List element.
+ * @return Validity: 0=unlimited, 1=once, >1 until this time stamp.
+ */
 GLOBAL time_t
 Lists_GetValidity(const struct list_elem *e)
 {
@@ -64,44 +82,59 @@ Lists_GetValidity(const struct list_elem *e)
        return e->valid_until;
 }
 
+/**
+ * Get first list element of a list.
+ *
+ * @param h List head.
+ * @return Pointer to first list element.
+ */
 GLOBAL struct list_elem*
 Lists_GetFirst(const struct list_head *h)
 {
+       assert(h != NULL);
        return h->first;
 }
 
-
+/**
+ * Get next list element of a list.
+ *
+ * @param e Current list element.
+ * @return Pointer to next list element.
+ */
 GLOBAL struct list_elem*
 Lists_GetNext(const struct list_elem *e)
 {
+       assert(e != NULL);
        return e->next;
 }
 
 /**
  * Add a new mask to a list.
  *
- * @param header List head.
+ * @param h List head.
  * @param Mask The IRC mask to add to the list.
  * @param ValidUntil 0: unlimited, 1: only once, t>1: until given time_t.
  * @param Reason Reason string or NULL, if no reason should be saved.
  * @return true on success, false otherwise.
  */
 bool
-Lists_Add(struct list_head *header, const char *Mask, time_t ValidUntil,
+Lists_Add(struct list_head *h, const char *Mask, time_t ValidUntil,
          const char *Reason)
 {
        struct list_elem *e, *newelem;
 
-       assert( header != NULL );
-       assert( Mask != NULL );
+       assert(h != NULL);
+       assert(Mask != NULL);
 
-       if (Lists_CheckDupeMask(header, Mask )) return true;
+       if (Lists_CheckDupeMask(h, Mask))
+               return true;
 
-       e = Lists_GetFirst(header);
+       e = Lists_GetFirst(h);
 
        newelem = malloc(sizeof(struct list_elem));
-       if( ! newelem ) {
-               Log( LOG_EMERG, "Can't allocate memory for new Ban/Invite entry!" );
+       if (!newelem) {
+               Log(LOG_EMERG,
+                   "Can't allocate memory for new list entry!");
                return false;
        }
 
@@ -118,43 +151,57 @@ Lists_Add(struct list_head *header, const char *Mask, time_t ValidUntil,
                newelem->reason = NULL;
        newelem->valid_until = ValidUntil;
        newelem->next = e;
-       header->first = newelem;
+       h->first = newelem;
 
        return true;
 }
 
-
+/**
+ * Delete a list element from a list.
+ *
+ * @param h List head.
+ * @param p Pointer to previous list element or NULL, if there is none.
+ * @param victim List element to delete.
+ */
 static void
-Lists_Unlink(struct list_head *header, struct list_elem *p, struct list_elem *victim)
+Lists_Unlink(struct list_head *h, struct list_elem *p, struct list_elem *victim)
 {
        assert(victim != NULL);
-       assert(header != NULL);
+       assert(h != NULL);
 
-       if (p) p->next = victim->next;
-       else header->first = victim->next;
+       if (p)
+               p->next = victim->next;
+       else
+               h->first = victim->next;
 
        if (victim->reason)
                free(victim->reason);
+
        free(victim);
 }
 
-
+/**
+ * Delete a given IRC mask from a list.
+ *
+ * @param h List head.
+ * @param Mask IRC mask to delete from the list.
+ */
 GLOBAL void
-Lists_Del(struct list_head *header, const char *Mask)
+Lists_Del(struct list_head *h, const char *Mask)
 {
        struct list_elem *e, *last, *victim;
 
-       assert( header != NULL );
-       assert( Mask != NULL );
+       assert(h != NULL);
+       assert(Mask != NULL);
 
        last = NULL;
-       e = Lists_GetFirst(header);
-       while( e ) {
-               if(strcasecmp( e->mask, Mask ) == 0 ) {
+       e = Lists_GetFirst(h);
+       while (e) {
+               if (strcasecmp(e->mask, Mask) == 0) {
                        LogDebug("Deleted \"%s\" from list", e->mask);
                        victim = e;
                        e = victim->next;
-                       Lists_Unlink(header, last, victim);
+                       Lists_Unlink(h, last, victim);
                        continue;
                }
                last = e;
@@ -162,7 +209,11 @@ Lists_Del(struct list_head *header, const char *Mask)
        }
 }
 
-
+/**
+ * Free a complete list.
+ *
+ * @param head List head.
+ */
 GLOBAL void
 Lists_Free(struct list_head *head)
 {
@@ -173,7 +224,7 @@ Lists_Free(struct list_head *head)
        e = head->first;
        head->first = NULL;
        while (e) {
-               LogDebug("Deleted \"%s\" from invite list" , e->mask);
+               LogDebug("Deleted \"%s\" from list" , e->mask);
                victim = e;
                e = e->next;
                if (victim->reason)
@@ -182,79 +233,93 @@ Lists_Free(struct list_head *head)
        }
 }
 
-
+/**
+ * Check if an IRC mask is already contained in a list.
+ *
+ * @param h List head.
+ * @param Mask IRC mask to test.
+ * @return true if mask is already stored in the list, false otherwise.
+ */
 GLOBAL bool
 Lists_CheckDupeMask(const struct list_head *h, const char *Mask )
 {
        struct list_elem *e;
        e = h->first;
        while (e) {
-               if (strcasecmp( e->mask, Mask ) == 0 )
+               if (strcasecmp(e->mask, Mask) == 0)
                        return true;
                e = e->next;
        }
        return false;
 }
 
-
+/**
+ * Generate a valid IRC mask from "any" string given.
+ *
+ * Attention: This mask is only valid until the next call to Lists_MakeMask(),
+ * because a single global buffer ist used! You have to copy the generated
+ * mask to some sane location yourself!
+ *
+ * @param Pattern Source string to generate an IRC mask for.
+ * @return Pointer to global result buffer.
+ */
 GLOBAL const char *
 Lists_MakeMask(const char *Pattern)
 {
-       /* This function generats a valid IRC mask of "any" string. This
-        * mask is only valid until the next call to Lists_MakeMask(),
-        * because a single global buffer is used. You have to copy the
-        * generated mask to some sane location yourself! */
-
        static char TheMask[MASK_LEN];
        char *excl, *at;
 
-       assert( Pattern != NULL );
+       assert(Pattern != NULL);
 
-       excl = strchr( Pattern, '!' );
-       at = strchr( Pattern, '@' );
+       excl = strchr(Pattern, '!');
+       at = strchr(Pattern, '@');
 
-       if(( at ) && ( at < excl )) excl = NULL;
+       if (at && at < excl)
+               excl = NULL;
 
-       if(( ! at ) && ( ! excl ))
-       {
+       if (!at && !excl) {
                /* Neither "!" nor "@" found: use string as nick name */
-               strlcpy( TheMask, Pattern, sizeof( TheMask ) - 5 );
-               strlcat( TheMask, "!*@*", sizeof( TheMask ));
+               strlcpy(TheMask, Pattern, sizeof(TheMask) - 5);
+               strlcat(TheMask, "!*@*", sizeof(TheMask));
                return TheMask;
        }
 
-       if(( ! at ) && ( excl ))
-       {
+       if (!at && excl) {
                /* Domain part is missing */
-               strlcpy( TheMask, Pattern, sizeof( TheMask ) - 3 );
-               strlcat( TheMask, "@*", sizeof( TheMask ));
+               strlcpy(TheMask, Pattern, sizeof(TheMask) - 3);
+               strlcat(TheMask, "@*", sizeof(TheMask));
                return TheMask;
        }
 
-       if(( at ) && ( ! excl ))
-       {
+       if (at && !excl) {
                /* User name is missing */
                *at = '\0'; at++;
-               strlcpy( TheMask, Pattern, sizeof( TheMask ) - 5 );
-               strlcat( TheMask, "!*@", sizeof( TheMask ));
-               strlcat( TheMask, at, sizeof( TheMask ));
+               strlcpy(TheMask, Pattern, sizeof(TheMask) - 5);
+               strlcat(TheMask, "!*@", sizeof(TheMask));
+               strlcat(TheMask, at, sizeof(TheMask));
                return TheMask;
        }
 
        /* All parts (nick, user and domain name) are given */
-       strlcpy( TheMask, Pattern, sizeof( TheMask ));
+       strlcpy(TheMask, Pattern, sizeof(TheMask));
        return TheMask;
 } /* Lists_MakeMask */
 
-
+/**
+ * Check if a client is listed in a list.
+ *
+ * @param h List head.
+ * @param Client Client to check.
+ * @return true if client is listed, false if not.
+ */
 bool
-Lists_Check( struct list_head *header, CLIENT *Client)
+Lists_Check( struct list_head *h, CLIENT *Client)
 {
        struct list_elem *e, *last, *next;
 
-       assert( header != NULL );
+       assert(h != NULL);
 
-       e = header->first;
+       e = h->first;
        last = NULL;
 
        while (e) {
@@ -263,16 +328,16 @@ Lists_Check( struct list_head *header, CLIENT *Client)
                        /* Entry is expired, delete it */
                        LogDebug("Deleted \"%s\" from list (expired).",
                                 e->mask);
-                       Lists_Unlink(header, last, e);
+                       Lists_Unlink(h, last, e);
                        e = next;
                        continue;
                }
                if (Match(e->mask, Client_Mask(Client))) {
-                       if (e->valid_until == 1 ) {
+                       if (e->valid_until == 1) {
                                /* Entry is valid only once, delete it */
                                LogDebug("Deleted \"%s\" from list (used).",
                                         e->mask);
-                               Lists_Unlink(header, last, e);
+                               Lists_Unlink(h, last, e);
                        }
                        return true;
                }
index 5dd1a68b8ae009752519e07f1392a87bfb6d0b0f..316b13454068c18f856170e4938190f9bab3a357 100644 (file)
@@ -29,16 +29,18 @@ struct list_head {
 GLOBAL struct list_elem *Lists_GetFirst PARAMS((const struct list_head *));
 GLOBAL struct list_elem *Lists_GetNext PARAMS((const struct list_elem *));
 
-GLOBAL bool Lists_Check PARAMS((struct list_head *head, CLIENT *client ));
-GLOBAL bool Lists_CheckDupeMask PARAMS((const struct list_head *head, const char *mask ));
+GLOBAL bool Lists_Check PARAMS((struct list_head *head, CLIENT *client));
+GLOBAL bool Lists_CheckDupeMask PARAMS((const struct list_head *head,
+                                       const char *mask));
 
-GLOBAL bool Lists_Add PARAMS((struct list_head *header, const char *Mask,
+GLOBAL bool Lists_Add PARAMS((struct list_head *h, const char *Mask,
                              time_t ValidUntil, const char *Reason));
-GLOBAL void Lists_Del PARAMS((struct list_head *head, const char *Mask ));
+GLOBAL void Lists_Del PARAMS((struct list_head *head, const char *Mask));
 
-GLOBAL bool Lists_AlreadyRegistered PARAMS(( const struct list_head *head, const char *Mask));
+GLOBAL bool Lists_AlreadyRegistered PARAMS((const struct list_head *head,
+                                           const char *Mask));
 
-GLOBAL void Lists_Free PARAMS(( struct list_head *head ));
+GLOBAL void Lists_Free PARAMS((struct list_head *head));
 
 GLOBAL const char *Lists_MakeMask PARAMS((const char *Pattern));
 GLOBAL const char *Lists_GetMask PARAMS((const struct list_elem *e));