Added doxygen comments on the last missing files

4 files changed, 153 insertions, 33 deletions

diff --git a/database/sqlite/administration/attempts.c b/database/sqlite/administration/attempts.c
index 8518e28..e1e5d19 100644
--- a/database/sqlite/administration/attempts.c
+++ b/database/sqlite/administration/attempts.c
@@ -1,6 +1,6 @@
 /* attempts.c  --  Functions for processing openvpn_attempts records
  *
- *  GPLv2 only - Copyright (C) 2008, 2009
+ *  GPLv2 only - Copyright (C) 2009
  *               David Sommerseth <dazo@users.sourceforge.net>
  *
  *  This program is free software; you can redistribute it and/or
@@ -19,6 +19,15 @@
  *
  */
 
+/**
+ * @file   sqlite/administration/attempts.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2009-04-09
+ *
+ * @brief  Functions for processing attempts entries in the database
+ *
+ */
+
 #include <string.h>
 #include <unistd.h>
 #include <assert.h>
@@ -47,6 +56,14 @@
 #include "../sqlite.h"
 
 
+/**
+ * Internal function.  Retrieves a list of all registered entries in the attempts table
+ *
+ * @param ctx  eurephiaCTX
+ * @param fmap eDBfieldMap containing the search query
+ *
+ * @return Returns a valid eurephia XML document on success, otherwise NULL
+ */
 xmlDoc *attempts_list(eurephiaCTX *ctx, eDBfieldMap *fmap) {
         dbresult *res = NULL;
         xmlDoc *doc = NULL;
@@ -105,6 +122,15 @@ xmlDoc *attempts_list(eurephiaCTX *ctx, eDBfieldMap *fmap) {
 }
 
 
+
+/**
+ * Internal function.  Resets the attempts counter for one or more entries in the database
+ *
+ * @param ctx  eurephiaCTX
+ * @param fmap eDBfieldMap defining which records to reset the attempts counter on
+ *
+ * @return Returns a valid eurephia XML document on success, otherwise NULL
+ */
 xmlDoc *attempts_reset(eurephiaCTX *ctx, eDBfieldMap *fmap) {
         dbresult *res = NULL;
         xmlDoc *ret = NULL;
@@ -131,6 +157,15 @@ xmlDoc *attempts_reset(eurephiaCTX *ctx, eDBfieldMap *fmap) {
         return ret;
 }
 
+
+/**
+ * Internal function.  Deletes an entry from the attempts log
+ *
+ * @param ctx  eurephiaCTX
+ * @param fmap eDBfieldMap containing the entry/entries to delete
+ *
+ * @return Returns a valid eurephia XML document on success, otherwise NULL
+ */
 xmlDoc *attempts_delete(eurephiaCTX *ctx, eDBfieldMap *fmap) {
         dbresult *res = NULL;
         xmlDoc *ret = NULL;
diff --git a/database/sqlite/administration/blacklist.c b/database/sqlite/administration/blacklist.c
index 7719ccc..12130c3 100644
--- a/database/sqlite/administration/blacklist.c
+++ b/database/sqlite/administration/blacklist.c
@@ -1,6 +1,6 @@
 /* blacklist.c  --  Functions for processing openvpn_blacklist records
  *
- *  GPLv2 only - Copyright (C) 2008, 2009
+ *  GPLv2 only - Copyright (C) 2009
  *               David Sommerseth <dazo@users.sourceforge.net>
  *
  *  This program is free software; you can redistribute it and/or
@@ -19,6 +19,15 @@
  *
  */
 
+/**
+ * @file   sqlite/administration/blacklist.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2009-05-09
+ *
+ * @brief  Functions for administering the blacklist table
+ *
+ */
+
 #include <string.h>
 #include <unistd.h>
 #include <assert.h>
@@ -47,6 +56,14 @@
 #include "../sqlite.h"
 
 
+/**
+ * Internal function. Retrieves a list of all registered entries in the blacklist table
+ *
+ * @param ctx  eurephiaCTX
+ * @param fmap eDBfieldMap containing the search query
+ *
+ * @return Returns a valid eurephia XML document on success, otherwise NULL
+ */
 xmlDoc *blacklist_list(eurephiaCTX *ctx, eDBfieldMap *fmap) {
         dbresult *res = NULL;
         xmlDoc *doc = NULL;
@@ -104,6 +121,14 @@ xmlDoc *blacklist_list(eurephiaCTX *ctx, eDBfieldMap *fmap) {
 }
 
 
+/**
+ * Internal function.  Registers a new entry in the blacklist.
+ *
+ * @param ctx   eurephiaCTX
+ * @param fmap  eDBfieldMap containing the entry to be registered
+ *
+ * @return Returns an eurephia ResultMsg XML document, with success message or an error message
+ */
 xmlDoc *blacklist_add(eurephiaCTX *ctx, eDBfieldMap *fmap) {
         dbresult *res = NULL;
         xmlDoc *ret = NULL;
@@ -127,6 +152,15 @@ xmlDoc *blacklist_add(eurephiaCTX *ctx, eDBfieldMap *fmap) {
         return ret;
 }
 
+
+/**
+ * Internal function.  Deletes an entry from the blacklist
+ *
+ * @param ctx   eurephiaCTX
+ * @param fmap  eDBfieldMap containing the entry to be deleted
+ *
+ * @return Returns an eurephia ResultMsg XML document, with success message or an error message
+ */
 xmlDoc *blacklist_delete(eurephiaCTX *ctx, eDBfieldMap *fmap) {
         dbresult *res = NULL;
         xmlDoc *ret = NULL;
diff --git a/database/sqlite/administration/firewalladmin.c b/database/sqlite/administration/firewalladmin.c
index 0e8e91a..378f265 100644
--- a/database/sqlite/administration/firewalladmin.c
+++ b/database/sqlite/administration/firewalladmin.c
@@ -19,6 +19,15 @@
  *
  */
 
+/**
+ * @file   sqlite/administration/firewalladmin.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2009-03-28
+ *
+ * @brief  Functions for managing firewall profiles
+ *
+ */
+
 #include <string.h>
 #include <unistd.h>
 #include <assert.h>
@@ -52,6 +61,14 @@
 void xmlReplaceChars(xmlChar *str, char s, char r);
 
 
+/**
+ * Internal function.  Queries the database for a list of user-certificate links
+ *
+ * @param ctx      eurephiaCTX
+ * @param fmap     eDBfieldMap containing the search criteria
+ *
+ * @return Returns a valid eurephia XML document on success, otherwise NULL
+ */
 xmlDoc *fwadmin_search(eurephiaCTX *ctx, eDBfieldMap *fmap) {
         dbresult *res = NULL;
         xmlDoc *doc = NULL;
@@ -82,7 +99,7 @@ xmlDoc *fwadmin_search(eurephiaCTX *ctx, eDBfieldMap *fmap) {
                                   NULL, fmap, "accessprofile, uid, c.certid");
         if( res == NULL ) {
                 eurephia_log(ctx, LOG_ERROR, 0, "Error querying the database for firewall profiles");
-                return 0;
+                return NULL;
         }
 
         eurephiaXML_CreateDoc(ctx, 1, "firewall_profiles", &doc, &root_n);
@@ -135,6 +152,14 @@ xmlDoc *fwadmin_search(eurephiaCTX *ctx, eDBfieldMap *fmap) {
 }
 
 
+/**
+ * Internal function.  Registers a new firewall profile
+ *
+ * @param ctx   eurephiaCTX
+ * @param fmap  eDBfieldMap containing information about the new profile
+ *
+ * @return Returns an eurephia ResultMsg XML document, with success message or an error message
+ */
 xmlDoc *fwadmin_add(eurephiaCTX *ctx, eDBfieldMap *fmap) {
         dbresult *res = NULL;
         xmlDoc *ret = NULL;
@@ -158,6 +183,14 @@ xmlDoc *fwadmin_add(eurephiaCTX *ctx, eDBfieldMap *fmap) {
 }
 
 
+/**
+ * Internal function.  Deletes firewall profile(s) from the database
+ *
+ * @param ctx   eurephiaCTX
+ * @param fmap  eDBfieldMap containing information about the profile(s) to be deleted
+ *
+ * @return Returns an eurephia ResultMsg XML document, with success message or an error message
+ */
 xmlDoc *fwadmin_delete(eurephiaCTX *ctx, eDBfieldMap *fmap) {
         dbresult *res = NULL;
         xmlDoc *ret = NULL;
@@ -212,26 +245,17 @@ xmlDoc *fwadmin_delete(eurephiaCTX *ctx, eDBfieldMap *fmap) {
 }
 
 
-// The search XML document format is:
-//    <eurephia format="1">
-//        <firewall_profiles mode="{search|add|delete}">
-//            <fieldMapping table="fwprofiles">
-//               <{field name}>{search value}</{field name}>
-//            </fieldMapping>
-//        </firewall_profiles>
-//    </eurehpia>
-//
-//  It can be several field name tags to limit the search even more.
-//  For the add mode, the fw_profile field name tag must be present.
-//
-xmlDoc *eDBadminFirewallProfiles(eurephiaCTX *ctx, xmlDoc *srch) {
+/**
+ * @copydoc eDBadminFirewallProfiles()
+ */
+xmlDoc *eDBadminFirewallProfiles(eurephiaCTX *ctx, xmlDoc *xmlqry) {
         eDBfieldMap *fmap = NULL;
         char *mode = NULL;
         xmlDoc *resxml = NULL;
         xmlNode *root_n = NULL, *fieldmap_n = NULL;
 
         DEBUG(ctx, 20, "Function call: eDBadminFirewallProfiles(ctx, {xmlDoc})");
-        assert( (ctx != NULL) && (srch != NULL) );
+        assert( (ctx != NULL) && (xmlqry != NULL) );
 
         if( (ctx->context_type != ECTX_ADMIN_CONSOLE) && (ctx->context_type != ECTX_ADMIN_WEB) ) {
                 eurephia_log(ctx, LOG_CRITICAL, 0,
@@ -239,7 +263,7 @@ xmlDoc *eDBadminFirewallProfiles(eurephiaCTX *ctx, xmlDoc *srch) {
                 return NULL;
         }
 
-        root_n = eurephiaXML_getRoot(ctx, srch, "firewall_profiles", 1);
+        root_n = eurephiaXML_getRoot(ctx, xmlqry, "firewall_profiles", 1);
         if( root_n == NULL ) {
                 eurephia_log(ctx, LOG_CRITICAL, 0, "Invalid XML input.");
                 return NULL;
@@ -269,4 +293,3 @@ xmlDoc *eDBadminFirewallProfiles(eurephiaCTX *ctx, xmlDoc *srch) {
         eDBfreeMapping(fmap);
         return resxml;
 }
-
diff --git a/database/sqlite/administration/usercerts.c b/database/sqlite/administration/usercerts.c
index 6dd091c..408891f 100644
--- a/database/sqlite/administration/usercerts.c
+++ b/database/sqlite/administration/usercerts.c
@@ -1,4 +1,4 @@
-/* usercerts.c  --  Admin functions - user-certitificate table
+/* usercerts.c  --  Admin functions - user-certificate table
  *
  *  GPLv2 only - Copyright (C) 2008, 2009
  *               David Sommerseth <dazo@users.sourceforge.net>
@@ -19,6 +19,15 @@
  *
  */
 
+/**
+ * @file   sqlite/administration/usercerts.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2009-08-29
+ *
+ * @brief  Functions for working with the openvpn_usercerts table
+ *
+ */
+
 #include <string.h>
 #include <unistd.h>
 #include <assert.h>
@@ -50,6 +59,16 @@
 
 void xmlReplaceChars(xmlChar *str, char s, char r);
 
+
+/**
+ * Internal function.  Queries the database for a list of user-certificate links
+ *
+ * @param ctx      eurephiaCTX
+ * @param where_m  eDBfieldMap containing the search criteria
+ * @param sortkeys String containing the sort order of the data
+ *
+ * @return Returns a valid eurephia XML document on success, otherwise NULL
+ */
 xmlDoc *usercerts_search(eurephiaCTX *ctx, eDBfieldMap *where_m, const char *sortkeys) {
         xmlDoc *list_xml = NULL;
         xmlNode *link_root_n = NULL, *link_n = NULL, *tmp_n = NULL;
@@ -126,6 +145,15 @@ xmlDoc *usercerts_search(eurephiaCTX *ctx, eDBfieldMap *where_m, const char *sor
 }
 
 
+/**
+ * Internal function.  Adds or deletes a user-certificate link
+ *
+ * @param ctx       eurephiaCTX
+ * @param mode      String containing the operation mode.  Must be "register" or "remove"
+ * @param usrcrt_m  eDBfieldMap containing information about the link to add or remove
+ *
+ * @return Returns an eurephia ResultMsg XML document, with success message or an error message
+ */
 xmlDoc *usercerts_add_del(eurephiaCTX *ctx, const char *mode, eDBfieldMap *usrcrt_m) {
         xmlDoc *res = NULL;
         dbresult *dbres = NULL;
@@ -168,6 +196,16 @@ xmlDoc *usercerts_add_del(eurephiaCTX *ctx, const char *mode, eDBfieldMap *usrcr
 }
 
 
+/**
+ * Internal function.  Updates a user-certs link in the database
+ *
+ * @param ctx      eurephiaCTX
+ * @param uicid    String containing the numeric record ID (uicid field) of the record to be updated
+ * @param usrcrt_m eDBfieldMap containing the new information for the record.  Only the fields being
+ *                 changed needs to be set.
+ *
+ * @return Returns an eurephia ResultMsg XML document, with success message or an error message
+ */
 xmlDoc *usercerts_update(eurephiaCTX *ctx, const char *uicid, eDBfieldMap *usrcrt_m) {
         xmlNode *where_n = NULL;
         eDBfieldMap *where_m = NULL;
@@ -215,19 +253,9 @@ xmlDoc *usercerts_update(eurephiaCTX *ctx, const char *uicid, eDBfieldMap *usrcr
 }
 
 
-// The XML document format:
-//    <eurephia format="1">
-//        <usercerts mode="{search|register|remove|update}" [uicid="{uicid}"]>
-//            <fieldMapping table="usercerts">
-//               <{field name}>{search value}</{field name}>
-//            </fieldMapping>
-//            [<sortfields>{field name}[, {field name},...]</sortfields>] <!-- Only for mode='search' -->
-//        </usercerts
-//    </eurehpia>
-//
-//  It can be several field name tags to limit the search even more.
-//  If mode is 'update' the 'uicid' attribute must be present in the usercerts tag.
-//
+/**
+ * @copydoc eDBadminUserCertsLink()
+ */
 xmlDoc *eDBadminUserCertsLink(eurephiaCTX *ctx, xmlDoc *usrcrt_xml) {
         xmlNode *usrcrt_n = NULL, *tmp_n = NULL;
         xmlDoc *resxml = NULL;