Added comments to sqlite.[ch]

1 files changed, 139 insertions, 13 deletions

diff --git a/database/sqlite/sqlite.c b/database/sqlite/sqlite.c
index 8646ea6..70ae682 100644
--- a/database/sqlite/sqlite.c
+++ b/database/sqlite/sqlite.c
@@ -19,6 +19,15 @@
  *
  */
 
+/**
+ * @file   sqlite.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief  Generic functions to simplify the SQLite3 integration.
+ *
+ */
+
 #include <string.h>
 #include <stdlib.h>
 #include <assert.h>
@@ -33,20 +42,30 @@
 #include <eurephia_directions.h>
 #include <eurephiadb_mapping.h>
 
-#define SQLITE_C
 #include "./sqlite.h"
 
 #ifdef MEMWATCH
 #include <memwatch.h>
 #endif
 
+/**
+ * @{
+ */
 #define btWHERE  0x001
 #define btINSERT 0x002
 #define btUPDATE 0x004
+/**
+ * @}
+ */
 
-dbresult *glob_results = NULL;
+dbresult *glob_results = NULL;  /**< A local pointer needed for the SQLite3 callback function */
 
-// Free up a dbresult structure
+/**
+ * Internal function.  Free up a dbresult structure.  This function is available via the
+ * the public macro sqlite_free_results() which is defined in sqlite.h
+ *
+ * @param inres Pointer to the dbresult structure to be freed
+ */
 void _sqlite_free_results(dbresult *inres) 
 {
         _sqlite_tuples *tup = NULL, *fld = NULL;
@@ -91,9 +110,17 @@ void _sqlite_free_results(dbresult *inres)
         free_nullsafe(NULL, inres);
 }
 
-
-// Callback function used by sqlite3_exec - populates a global variable glob_results.
-// The glob_results structure is allocated with a new address on each sqlite_query call
+/**
+ * Callback function used by sqlite3_exec - populates a global variable glob_results.
+ * The glob_results structure is allocated with a new address on each sqlite_query call
+ *
+ * @param NotUsed N/A
+ * @param argc    Number of fields in the result
+ * @param argv    Array pointer to the values of the fields
+ * @param colName Array pointer to the field names (column names)
+ *
+ * @return SQLite3 defines 0 for no errors, and 1 for errors.
+ */
 static int _cb_parse_result(void *NotUsed, int argc, char **argv, char **colName) 
 {
         // This callback function is called for each row returned by the query
@@ -198,9 +225,15 @@ static int _cb_parse_result(void *NotUsed, int argc, char **argv, char **colName
 }
 
 
-// A simpler way to fetch data from SQLite than to use sqlite3_exec with callback 
-// each time you want to do a query
-dbresult *sqlite_query(eurephiaCTX *ctx, char *fmt, ... ) { 
+/**
+ * Main function for query a SQLite3 database.
+ *
+ * @param ctx eurephiaCTX
+ * @param fmt The SQL query.  It supports stdarg to build up dynamic queries directly.
+ *
+ * @return Returns a pointer to a dbresult struct on success, otherwise NULL.
+ */
+dbresult *sqlite_query(eurephiaCTX *ctx, const char *fmt, ... ) {
         int rc;
         va_list ap;
         char *errMsg = NULL, *sql = NULL;
@@ -251,6 +284,14 @@ dbresult *sqlite_query(eurephiaCTX *ctx, char *fmt, ... ) {
         return glob_results;
 }
 
+/**
+ * Internal function.  Checks if the input string contains reserved words
+ *
+ * @param reserved_words Array containing the reserver words
+ * @param val Value to check against the reserved words
+ *
+ * @return Returns 1 if a reserverd word is found, otherwise 0
+ */
 inline int SQLreservedWord(char **reserved_words, const char *val) {
         int i;
 
@@ -264,6 +305,14 @@ inline int SQLreservedWord(char **reserved_words, const char *val) {
 }
 
 
+/**
+ * Internal function.  Creates a string with the value from a particular field in a eDBfieldMap and
+ * formats it properly according to its field type.
+ *
+ * @param ptr Pointer to the field in the eDBfieldMap
+ *
+ * @return Returns a string to be used within an SQL query.
+ */
 char *_build_value_string(eDBfieldMap *ptr) {
         char *reserved_datetime[] = {"CURRENT_TIMESTAMP", "CURRENT_TIME", "CURRENT_DATE", NULL};
         char *val = NULL;
@@ -297,7 +346,28 @@ char *_build_value_string(eDBfieldMap *ptr) {
         return val;
 }
 
+
+/**
+ * Wrapper macro, which appends a string to a destination string without exceeding the size
+ * of the destination buffer.
+ *
+ * @param dest Pointer to the destination buffer
+ * @param src  Pointer to the value being concatenated to the destination string.
+ * @param size Size of the destination buffer
+ */
 #define append_str(dest, src, size) strncat(dest, src, (size - strlen_nullsafe(dest)))
+
+
+/**
+ * Internal function.  Builds up a part of an SQL query, depending on the buildType.  The values
+ * are taken from a pointer to an eDBfieldMap keeping the values
+ *
+ * @param btyp Must be btWHERE, btINSERT or btUPDATE
+ * @param map  Pointer to a eDBfieldMap chain containing the values
+ *
+ * @return Returns a string with parts of the SQL query containing the dynamic variables on success,
+ *         otherwise NULL is returned.
+ */
 char *_build_sqlpart(int btyp, eDBfieldMap *map) {
         eDBfieldMap *ptr = NULL;
         char *ret = NULL;
@@ -408,6 +478,18 @@ char *_build_sqlpart(int btyp, eDBfieldMap *map) {
 }
 
 
+/**
+ * Queries an SQLite3 database by using an SQL stub plus values from a eDBfieldMap pointer chain
+ *
+ * @param ctx      eurephiaCTX
+ * @param qType    Query type, must be SQL_SELECT, SQL_INSERT, SQL_UPDATE or SQL_DELETE
+ * @param sqlstub  The generic part of the SQL query
+ * @param valMap   Values to be used in INSERT or UPDATE queries.  May be NULL if not SQL_INSERT or SQL_UPDATE
+ * @param whereMap Values to be used in the WHERE section of the SQL query
+ * @param sortkeys Only for SQL_SELECT, list of field names to sort the result by.
+ *
+ * @return Returns a pointer to a dbresult struct on success, otherwise NULL.
+ */
 dbresult *sqlite_query_mapped(eurephiaCTX *ctx, SQLqueryType qType, const char *sqlstub,
                               eDBfieldMap *valMap, eDBfieldMap *whereMap, const char *sortkeys)
 {
@@ -456,7 +538,12 @@ dbresult *sqlite_query_mapped(eurephiaCTX *ctx, SQLqueryType qType, const char *
         return res;
 }
 
-// Simple line-by-line result dumper
+/**
+ * Very simple dbresult dumper.  Will list out all records to the given FILE destination.
+ *
+ * @param dmp pointer to a FILE stream
+ * @param res pointe to the dbresults to be dumped
+ */
 void sqlite_dump_result(FILE *dmp, dbresult *res) {
         _sqlite_tuples *row = NULL, *field = NULL;
 
@@ -487,7 +574,17 @@ void sqlite_dump_result(FILE *dmp, dbresult *res) {
         // free(hdr);
 }
 
-// Retrieve a specific value from a dbresult structure
+/**
+ * Retrieves a particular value out of a dbresult
+ *
+ * @param res Pointer to dbresult
+ * @param row Row number (record number) to extract
+ * @param col Column number (field number) to extract
+ *
+ * @return Returns a pointer to the value if found, otherwise NULL is returned.
+ * @remark This function returns a pointer to the value insisde the dbresult struct.  If you want to use
+ *         this value after freeing the dbresult, you must make sure you copy this value yourself.
+ */
 char *sqlite_get_value(dbresult *res, int row, int col) {
         _sqlite_tuples *ptr = res->srch_tuples;
         
@@ -513,6 +610,20 @@ char *sqlite_get_value(dbresult *res, int row, int col) {
 
 
 #ifdef HAVE_LIBXML2
+/**
+ * Retrieves a particular value out of a dbresult and places it inside an xmlNode pointer.
+ *
+ * @param node    Pointer to the xmlNode
+ * @param xmltyp  Must be XML_ATTR or XML_NODE.  If XML_ATTR it will be added as an attribute/properties
+ *                to the given xmlNode.  If XML_NODE, it will be added as a child to the given xmlNode.
+ * @param inname  String containing the name of the attribute or XML tag. (Depending on xmltyp)
+ * @param res     Pointer to dbresult
+ * @param row     Row number (record number) to extract
+ * @param col     Column number (field number) to extract
+ *
+ * @return Returns a pointer to the xmlNode which got updated.  If xmltyp == XML_NODE it will point at
+ *         the newly added node.  On failure NULL will be returned.
+ */
 xmlNodePtr sqlite_xml_value(xmlNodePtr node, xmlFieldType xmltyp, char *inname, dbresult *res, int row, int col) {
         xmlChar *name = NULL, *data = NULL;
         xmlNodePtr retnode = NULL;
@@ -542,12 +653,27 @@ xmlNodePtr sqlite_xml_value(xmlNodePtr node, xmlFieldType xmltyp, char *inname,
 }
 #endif
 
-// Retrieve number of tuples in current dbresult structure
+
+/**
+ * Retrieve number of tuples in a given dbresult structure
+ *
+ * @param res Pointer to a dbresult
+ *
+ * @return Returns number of rows/number of tuples in the result.
+ */
 int sqlite_get_numtuples(dbresult *res) {
         return (res != NULL ? res->num_tuples : 0);
 }
 
-// Retrieve number of tuples in current dbresult structure
+
+/**
+ * Retrieve number of affected tuples in current dbresult structure.  This is only useful
+ * when called on a result from INSERT, UPDATE or DELETE queries.
+ *
+ * @param res Pointer to a dbresult
+ *
+ * @return Returns number of rows/tuples affected by the SQL query
+ */
 int sqlite_get_affected_rows(dbresult *res) {
         return (res != NULL ? res->affected_rows : 0);
 }