From 184ae2541ac312585c4358944385c7ed851c8d0b Mon Sep 17 00:00:00 2001 From: David Sommerseth Date: Tue, 8 Sep 2009 21:51:37 +0200 Subject: Added missing comments for the generic database/ files --- database/eurephiadb_mapping.c | 80 +++++++++++++++++++++++++++++++++-- database/eurephiadb_mapping.h | 97 ++++++++++++++++++++++++++++++++++++++----- database/eurephiadb_struct.h | 22 +++++++--- 3 files changed, 179 insertions(+), 20 deletions(-) (limited to 'database') 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 @@ -19,6 +19,19 @@ * */ +/** + * @file eurephiadb_mapping.c + * @author David Sommerseth + * @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 #include @@ -31,8 +44,10 @@ #include #include -// 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 + * @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 + * @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 -- cgit