Added missing comments for the generic database/ files

3 files changed, 179 insertions, 20 deletions

diff --git a/database/eurephiadb_mapping.c b/database/eurephiadb_mapping.c
index 52c9778..2541c4c 100644
--- a/database/eurephiadb_mapping.c
+++ b/database/eurephiadb_mapping.c
@@ -1,4 +1,4 @@
-/* eurephiadb_common.c  --  Common database functions, used by drivers
+/* eurephiadb_common.c  --  Database field mapping between database and the C code
  *
  *  GPLv2 only - Copyright (C) 2008, 2009
  *               David Sommerseth <dazo@users.sourceforge.net>
@@ -19,6 +19,19 @@
  *
  */
 
+/**
+ * @file   eurephiadb_mapping.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-12-06
+ *
+ * @brief  Database field mapping between database and the C code/programs
+ *
+ * This feature makes it possible to let each database driver implementation to
+ * use its own table and column/field names in the database, while having a
+ * unified interface for table names and field names in the application.
+ *
+ */
+
 #include <string.h>
 #include <assert.h>
 
@@ -31,8 +44,10 @@
 #include <eurephia_nullsafe.h>
 #include <passwd.h>
 
-// Simple mapping table for table_id to string.  Must match the order of the
-// defined tables in eurephia_mapping.h
+/**
+ * Simple mapping table for table_id to string.  Must match the order of the
+ * defined tables in eurephia_mapping.h
+ */
 const char *TABLE_NAME[] = {
         NULL,
         "users",                 // TABLE_USERS
@@ -45,7 +60,9 @@ const char *TABLE_NAME[] = {
         "firewall_profiles",     // TABLE_FWPROFILES
         NULL};
 
-// Simple mapping table for session status
+/**
+ * Simple mapping table for session status
+ */
 const char *SESSION_STATUS[] = {
         "UNKNOWN",
         "STARTED",
@@ -63,6 +80,11 @@ char *xmlGetAttrValue(xmlAttr *properties, const char *key);
 char *xmlExtractContent(xmlNode *n);
 
 
+/**
+ * Frees the memory used by a eDBfieldMap structure
+ *
+ * @param p Pointer to the eDBfieldMap to be freed
+ */
 void eDBfreeMapping(eDBfieldMap *p) {
         if( p == NULL ) {
                 return;
@@ -77,6 +99,16 @@ void eDBfreeMapping(eDBfieldMap *p) {
 }
 
 
+/**
+ * Internal function for mapping the unified eurephia mapping table from a table index.
+ * The table index is defined in eurephiadb_mapping.h, prefixed with TABLE_
+ *
+ * @param table table index (integer)
+ *
+ * @return Returns a pointer to the corresponding eDBfieldMap if table index is found, otherwise
+ *         NULL is returned.
+ * @see eurephiadb_mapping.h
+ */
 eDBfieldMap *eDBgetTableFieldMapping(int table) {
         eDBfieldMap *srcmap, *newmap = NULL, *ptr = NULL;
         int i;
@@ -138,6 +170,13 @@ eDBfieldMap *eDBgetTableFieldMapping(int table) {
 }
 
 
+/**
+ * Internal function for copying over a particular field from one eDBfieldMap to another one
+ *
+ * @param newmap The destination map to be updated
+ * @param dbmap  The source map where to copy the data from
+ * @param field  The ID of the field which is being copied over
+ */
 inline void eDBcopyMapAttribs(eDBfieldMap *newmap, eDBfieldMap *dbmap, int field) {
         int i = 0;
 
@@ -152,6 +191,19 @@ inline void eDBcopyMapAttribs(eDBfieldMap *newmap, eDBfieldMap *dbmap, int field
 }
 
 
+/**
+ * Create a eDBfieldMap to be used by the database driver, with the values from an fieldMapping XML node.
+ * This function will go through all fields in the XML tags, and associate the unified field names and
+ * table name with the database specific field/table names.
+ *
+ * @param ctx      eurephiaCTX
+ * @param dbmap    The database specific eDBfieldMap containing its own fields and table names
+ * @param tblalias If the SQL needs to use an alias, this alias prefix will be used for the fields
+ * @param fmapnode An xmlNode pointing at the fieldMapping node/tag.
+ *
+ * @return On success, a pointer to a eDBfieldMap specific for the database driver will be returned,
+ *         otherwise NULL.
+ */
 eDBfieldMap *eDBxmlMapping(eurephiaCTX *ctx, eDBfieldMap *dbmap, const char *tblalias, xmlNode *fmapnode) {
         eDBfieldMap *map = NULL, *ptr = NULL;
         char *fmap_table = NULL;
@@ -289,6 +341,17 @@ eDBfieldMap *eDBxmlMapping(eurephiaCTX *ctx, eDBfieldMap *dbmap, const char *tbl
 }
 
 
+/**
+ * Generates a database specific list which is comma separated for the database driver to
+ * use in the ORDER BY section of SQL queries.  The unified database fields are being translated
+ * into the database specific field names.
+ *
+ * @param tfmap     eDBfieldMap specific to the database driver.
+ * @param skeys_str Comma separated string containing the field names for the ORDER BY clause
+ *
+ * @return Returns a comma separated string with translated field names on success, otherwise NULL.
+ * @remark The resulting pointer is pointing at a static char pointer and should not be freed.
+ */
 char *eDBmkSortKeyString(eDBfieldMap *tfmap, const char *skeys_str) {
         eDBfieldMap *sk_map = NULL, *ptr1 = NULL;
         int i;
@@ -332,6 +395,15 @@ char *eDBmkSortKeyString(eDBfieldMap *tfmap, const char *skeys_str) {
         return sortkeys;
 }
 
+
+/**
+ * Tells which database fields in a eDBfieldMap are set and available.
+ *
+ * @param map eDBfieldMap containing the database specific mapping and field values set
+ *
+ * @return Returns a bit-wise OR'ed value of all fields in an eDBfieldMap which have their values
+ * set to something else than NULL.
+ */
 long int eDBmappingFieldsPresent(eDBfieldMap *map) {
         long int ret = 0;
         eDBfieldMap *p = NULL;
diff --git a/database/eurephiadb_mapping.h b/database/eurephiadb_mapping.h
index 954b953..932006e 100644
--- a/database/eurephiadb_mapping.h
+++ b/database/eurephiadb_mapping.h
@@ -22,25 +22,62 @@
  *
  */
 
+/**
+ * @file   eurephiadb_mapping.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-12-06
+ *
+ * @brief  Database field mapping between database and the C code/programs
+ *
+ * This feature makes it possible to let each database driver implementation to
+ * use its own table and column/field names in the database, while having a
+ * unified interface for table names and field names in the application.
+ *
+ * @remark The database may not have all assigned fields in the table as indicated here,
+ *         as this is a way how to get around queries which uses JOIN between more tables.
+ */
+
 #ifndef   	EUREPHIADB_MAPPING_H
 # define   	EUREPHIADB_MAPPING_H
 
+/**
+ *  Enumeration of different field types
+ */
 typedef enum eDBfieldType_e { ft_UNDEF, ft_INT, ft_STRING, ft_DATETIME, ft_PASSWD, ft_SETNULL } eDBfieldType;
+
+/**
+ *  Enumeration of different SQL filter types (IS NULL, =, !=,  <=, >=, >, <, etc)
+ */
 typedef enum eDBfieldFilterType_e { flt_NOTSET, flt_EQ, flt_NEQ, flt_LT, flt_LTE, flt_GT, flt_GTE } eDBfieldFilterType;
 
+/**
+ * Definition of the eDBfieldMap structure which maps a given numeric table ID and field ID
+ * to a specific field name.  This structure can also holds values for these fields to be used
+ * when doing SELECT, UPDATE or DELETE queries with WHERE sections and new values when doing
+ * INSERT INTO and UPDATE
+ */
 typedef struct _eDBfieldMap_s {
-        int tableid;
-        char *table_alias;
-        long field_id;
-        eDBfieldType field_type;
-        eDBfieldFilterType filter_type;
-        char *field_name;
-        char *value;
-        struct _eDBfieldMap_s *next;
+        int tableid;                      /**< @see TABLE_USERS */
+        char *table_alias;                /**< If the table needs an alias in the SQL query,
+                                             it should be set here*/
+        long field_id;                    /**< @see FIELD_NONE */
+        eDBfieldType field_type;          /**< Defines what kind of data this field stores */
+        eDBfieldFilterType filter_type;   /**< Only for WHERE sections, defines what kind of filter
+                                               mode to use  */
+        char *field_name;                 /**< Name of the field as a string */
+        char *value;                      /**< Value of the field */
+        struct _eDBfieldMap_s *next;      /**< Creates a pointer chain */
 } eDBfieldMap;
 
 extern const char *SESSION_STATUS[];
 
+/**
+ * TABLE ID definitions
+ *
+ * Gives each table needed for eurephia a numeric ID.  These IDs are sequential numbers, starting on 1
+ * and being increased by 1.
+ * @{
+ */
 #define TABLE_USERS          0x01
 #define TABLE_CERTS          0x02
 #define TABLE_USERCERTS      0x03
@@ -49,9 +86,19 @@ extern const char *SESSION_STATUS[];
 #define TABLE_BLACKLIST      0x06
 #define TABLE_EUREPHIAADMACC 0x07
 #define TABLE_FWPROFILES     0x08
+/**
+ * @}
+ */
 
-#define FIELD_NONE        0x0000000
-#define FIELD_RECID       0x0000001  // Primary keys
+/**
+ * FIELD ID definitions
+ *
+ * Gives each table needed for eurephia a numeric ID.  These IDs are increased by 2^x as these
+ * fields can be processed in a bit-wise manner by some functions.
+ * @{
+ */
+#define FIELD_NONE        0x0000000 /**< Special field */
+#define FIELD_RECID       0x0000001 /**< Special field, should be used to indicate primary key of the table */
 #define FIELD_UID         0x0000002
 #define FIELD_CERTID      0x0000004
 #define FIELD_UNAME       0x0000008
@@ -86,10 +133,16 @@ extern const char *SESSION_STATUS[];
 
 #define FIELD_DESCR       0x4000000
 #define FIELD_FWPROFILE   0x8000000
+/**
+ * @}
+ */
 
 
 #ifdef EUREPHIADB_MAPPING_C
 
+/**
+ * Unified eurephia field names for the 'users' table
+ */
 static eDBfieldMap eTblMap_user[] = {
         {TABLE_USERS, NULL, FIELD_RECID,       ft_INT,      flt_EQ, "uid",         NULL, NULL},
         {TABLE_USERS, NULL, FIELD_UNAME,       ft_STRING,   flt_EQ, "username",    NULL, NULL},
@@ -100,6 +153,9 @@ static eDBfieldMap eTblMap_user[] = {
         {0, NULL, 0, ft_UNDEF, flt_NOTSET, NULL, NULL, NULL}
 };
 
+/**
+ * Unified eurephia field names for the 'certificates' table
+ */
 static eDBfieldMap eTblMap_certificates[] = {
         {TABLE_CERTS, NULL, FIELD_RECID,       ft_INT,      flt_EQ, "certid",      NULL, NULL},
         {TABLE_CERTS, NULL, FIELD_CERTDEPTH,   ft_INT,      flt_EQ, "depth",       NULL, NULL},
@@ -111,6 +167,9 @@ static eDBfieldMap eTblMap_certificates[] = {
         {0, NULL, 0, ft_UNDEF, flt_NOTSET, NULL, NULL, NULL}
 };
 
+/**
+ * Unified eurephia field names for the 'lastlog' table
+ */
 static eDBfieldMap eTblMap_lastlog[] = {
         {TABLE_LASTLOG, NULL, FIELD_UID,         ft_INT,      flt_EQ, "uid",       NULL, NULL},
         {TABLE_LASTLOG, NULL, FIELD_CERTID,      ft_INT,      flt_EQ, "certid",    NULL, NULL},
@@ -126,6 +185,9 @@ static eDBfieldMap eTblMap_lastlog[] = {
         {0, NULL, 0, ft_UNDEF, flt_NOTSET, NULL, NULL, NULL}
 };
 
+/**
+ * Unified eurephia field names for the 'attempts log' table
+ */
 static eDBfieldMap eTblMap_attempts[] = {
         {TABLE_ATTEMPTS, NULL, FIELD_UNAME,       ft_STRING,   flt_EQ, "username",    NULL, NULL},
         {TABLE_ATTEMPTS, NULL, FIELD_REMOTEIP,    ft_STRING,   flt_EQ, "ip",          NULL, NULL},
@@ -137,6 +199,10 @@ static eDBfieldMap eTblMap_attempts[] = {
         {0, NULL, 0, ft_UNDEF, flt_NOTSET, NULL, NULL, NULL}
 };
 
+
+/**
+ * Unified eurephia field names for the 'blacklist' table
+ */
 static eDBfieldMap eTblMap_blacklist[] = {
         {TABLE_BLACKLIST, NULL, FIELD_UNAME,       ft_STRING,   flt_EQ, "username",     NULL, NULL},
         {TABLE_BLACKLIST, NULL, FIELD_REMOTEIP,    ft_STRING,   flt_EQ, "ip",           NULL, NULL},
@@ -147,6 +213,10 @@ static eDBfieldMap eTblMap_blacklist[] = {
         {0, NULL, 0, ft_UNDEF, flt_NOTSET, NULL, NULL, NULL}
 };
 
+
+/**
+ * Unified eurephia field names for the 'usercerts' table
+ */
 static eDBfieldMap eTblMap_usercerts[] = {
         {TABLE_USERCERTS, NULL, FIELD_UID,        ft_INT, flt_EQ,  "uid",            NULL, NULL},
         {TABLE_USERCERTS, NULL, FIELD_CERTID,     ft_INT, flt_EQ,  "certid",         NULL, NULL},
@@ -156,6 +226,10 @@ static eDBfieldMap eTblMap_usercerts[] = {
         {0, NULL, FIELD_NONE, ft_UNDEF, flt_NOTSET, NULL, NULL, NULL}
 };
 
+
+/**
+ * Unified eurephia field names for the 'eurephia_adminaccess' table
+ */
 static eDBfieldMap eTblMap_eurephiaadmacc[] = {
         {TABLE_EUREPHIAADMACC, NULL, FIELD_UID,       ft_INT,    flt_EQ, "uid",           NULL, NULL},
         {TABLE_EUREPHIAADMACC, NULL, FIELD_INTERFACE, ft_STRING, flt_EQ, "interface",     NULL, NULL},
@@ -163,6 +237,9 @@ static eDBfieldMap eTblMap_eurephiaadmacc[] = {
         {0, NULL, FIELD_NONE, ft_UNDEF, flt_NOTSET, NULL, NULL, NULL}
 };
 
+/**
+ * Unified eurephia field names for the 'accessprofiles' table
+ */
 static eDBfieldMap eTblMap_fwprofiles[] = {
         {TABLE_FWPROFILES,   NULL,     FIELD_DESCR,      ft_STRING  , flt_EQ, "description",   NULL, NULL},
         {TABLE_FWPROFILES,   NULL,     FIELD_FWPROFILE,  ft_STRING  , flt_EQ, "fwprofile",     NULL, NULL},
diff --git a/database/eurephiadb_struct.h b/database/eurephiadb_struct.h
index da45f4e..657e838 100644
--- a/database/eurephiadb_struct.h
+++ b/database/eurephiadb_struct.h
@@ -19,18 +19,28 @@
  *
  */
 
+/**
+ * @file   eurephiadb_struct.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-11-05
+ *
+ * @brief  Definition of the eDBconn struct, a database independent
+ *         connection handle
+ *
+ */
+
 #ifndef   	EUREPHIADB_STRUCT_H_
 # define   	EUREPHIADB_STRUCT_H_
 
 #include "eurephia_values_struct.h"
 
-//
-//  Struct containing connection to the database we are using
-//
+/**
+ *  Struct containing connection to the database we are using
+ */
 typedef struct {
-        void *dbhandle;
-        char *dbname;
-        eurephiaVALUES *config;
+        void *dbhandle;         /**< The DB handle used for the connection */
+        char *dbname;           /**< String with name of database, used in logs */
+        eurephiaVALUES *config; /**< eurephia config parameters retrieved from the database */
 } eDBconn;
 
 #endif