1 files changed, 76 insertions, 4 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;