Added doxygen comments for xmlparser.[ch] and pgsql.c

3 files changed, 188 insertions, 2 deletions

diff --git a/server/parser/pgsql.c b/server/parser/pgsql.c
index 407e0cd..fe5aa9c 100644
--- a/server/parser/pgsql.c
+++ b/server/parser/pgsql.c
@@ -35,6 +35,13 @@
 #include <xmlparser.h>
 
 
+/**
+ * Connect to a database, based on the given configuration
+ *
+ * @param cfg eurephiaVALUES containing the configuration
+ *
+ * @return Returns a database handler
+ */
 void *db_connect(eurephiaVALUES *cfg) {
 	PGconn *dbc = NULL;
 
@@ -60,11 +67,75 @@ void *db_connect(eurephiaVALUES *cfg) {
 }
 
 
+/**
+ * Disconnect from the database
+ *
+ * @param dbc Pointer to the database handle to be disconnected.
+ */
 void db_disconnect(void *dbc) {
 	PQfinish((PGconn *) dbc);
 }
 
 
+/**
+ * This function does INSERT SQL queries based on an XML document (sqldata) which contains
+ * all information about table, fields and records to be inserted.  For security and performance,
+ * this function uses prepared SQL statements.
+ *
+ * This function is PostgreSQL specific.
+ *
+ * @param dbc     Database handler to a PostgreSQL
+ * @param sqldoc  sqldata XML document containing the data to be inserted.
+ *
+ * The sqldata XML document must be formated like this:
+ * @code
+ * <sqldata table="{table name}" [key="{field name}">
+ *    <fields>
+ *       <field fid="{integer}">{field name}</field>
+ *       ...
+ *       ...
+ *       <field fid="{integer_n}">{field name 'n'}</field>
+ *    </fields>
+ *    <records>
+ *       <record>
+ *          <value fid="{integer} [type="{data type}"] [hash="{hash type}">{value for field 'fid'</value>
+ *          ...
+ *          ...
+ *          <value fid="{integer_n}">{value for field 'fid_n'</value>
+ *       </record>
+ *       ...
+ *       ...
+ *       ...
+ *    </records>
+ * </sqldata>
+ * @endcode
+ * The 'sqldata' root tag must contain a 'table' attribute.  This must contain the a name of a table
+ * in the database.  If the 'key' attribute is set, the function will return the that field value for
+ * each INSERT query, using INSERT ... RETURNING {field name}.  The sqldata root tag must then have
+ * two children, 'fields' and 'records'.
+ *
+ * The 'fields' tag need to contain 'field' children tags for each field to insert data for.  Each
+ * field in the fields tag must be assigned a unique integer.
+ *
+ * The 'records' tag need to contain 'record' children tags for each record to be inserted.  Each
+ * record tag needs to have 'value' tags for each field which is found in the 'fields' section.
+ *
+ * The 'value' tags must have a 'fid' attribute.  This is the link between the field name in the
+ * 'fields' section and the value to be inserted.
+ *
+ * The 'type' attribute may be used as well, but the only supported data type supported to this
+ * attribute is 'xmlblob'.  In this case, the contents of the 'value' tag must be more XML tags.
+ * These tags will then be serialised to a string which is inserted into the database.
+ *
+ * The 'hash' attribute of the 'value' tag can be set to 'sha1'.  This will make do a SHA1 hash
+ * calculation of the value and this hash value will be used for the insert.
+ *
+ * @return Returns an eurephiaVALUES list containing information about each record which was inserted.
+ *         If the 'key' attribute is not set in the 'sqldata' tag, the OID value of each record will be
+ *         saved.  If the table do not support OIDs, the value will be '0'.  Otherwise the contents of
+ *         the defined field name will be returned.  If one of the INSERT queries fails, it will abort
+ *         further processing and the function will return NULL.
+ */
 eurephiaVALUES *pgsql_INSERT(PGconn *dbc, xmlDoc *sqldoc) {
 	xmlNode *root_n = NULL, *fields_n = NULL, *recs_n = NULL, *ptr_n = NULL, *val_n = NULL;
 	char **field_ar = NULL, *fields = NULL, **value_ar = NULL, *values = NULL, *table = NULL, 
@@ -240,6 +311,18 @@ eurephiaVALUES *pgsql_INSERT(PGconn *dbc, xmlDoc *sqldoc) {
 }
 
 
+/**
+ * Registers information into the 'systems' and 'systems_hostname' tables, based on the
+ * summary/report XML file from rteval.
+ *
+ * @param indbc      Database handler where to perform the SQL queries
+ * @param xslt       A pointer to a parsed 'xmlparser.xsl' XSLT template
+ * @param summaryxml The XML report from rteval
+ *
+ * @return Returns a value > 0 on success, which is a unique reference to the system of the report.
+ *         If the function detects that this system is already registered, the 'syskey' reference will
+ *         be reused.  On errors, -1 will be returned.
+ */
 int db_register_system(void *indbc, xsltStylesheet *xslt, xmlDoc *summaryxml) {
 	PGconn *dbc = (PGconn *) indbc;
 	PGresult *dbres = NULL;
@@ -353,6 +436,18 @@ int db_register_system(void *indbc, xsltStylesheet *xslt, xmlDoc *summaryxml) {
 }
 
 
+/**
+ * Registers information into the 'rtevalruns' and 'rtevalruns_details' tables
+ *
+ * @param indbc         Database handler where to perform the SQL queries
+ * @param xslt          A pointer to a parsed 'xmlparser.xsl' XSLT template
+ * @param summaryxml    The XML report from rteval
+ * @param syskey        A positive integer containing the return value from db_register_system()
+ * @param report_fname  A string containing the filename of the report.
+ *
+ * @return Returns a positive integer which references the 'rterid' value (RTEvalRunID) on success,
+ *         otherwise -1 is returned.
+ */
 int db_register_rtevalrun(void *indbc, xsltStylesheet *xslt, xmlDoc *summaryxml,
 			  int syskey, const char *report_fname)
 {
@@ -433,6 +528,16 @@ int db_register_rtevalrun(void *indbc, xsltStylesheet *xslt, xmlDoc *summaryxml,
 }
 
 
+/**
+ * Registers data returned from cyclictest into the database.
+ *
+ * @param indbc      Database handler where to perform the SQL queries
+ * @param xslt       A pointer to a parsed 'xmlparser.xsl' XSLT template
+ * @param summaryxml The XML report from rteval
+ * @param rterid     A positive integer referencing the rteval run ID, returned from db_register_rtevalrun()
+ *
+ * @return Returns 1 on success, otherwise -1
+ */
 int db_register_cyclictest(void *indbc, xsltStylesheet *xslt, xmlDoc *summaryxml, int rterid) {
 	PGconn *dbc = (PGconn *) indbc;
 	int result = -1;
diff --git a/server/parser/xmlparser.c b/server/parser/xmlparser.c
index 70308d0..a5169f4 100644
--- a/server/parser/xmlparser.c
+++ b/server/parser/xmlparser.c
@@ -32,6 +32,14 @@
 #include <sha1.h>
 
 
+/**
+ * Simple strdup() function which encapsulates the string in single quotes,
+ * which is needed for XSLT parameter values
+ *
+ * @param str The string to be strdup'ed and encapsulated
+ *
+ * @return Returns a pointer to the new buffer.
+ */
 static char *encapsString(const char *str) {
         char *ret = NULL;
 
@@ -47,6 +55,15 @@ static char *encapsString(const char *str) {
 }
 
 
+/**
+ * Converts an integer to string an encapsulates the value in single quotes,
+ * which is needed for XSLT parameter values.
+ *
+ * @param val Integer value to encapsulate
+ *
+ * @return Returns a pointer to a new buffer with the encapsulated integer value.  This
+ *         buffer must be free'd after usage.
+ */
 static char *encapsInt(const unsigned int val) {
         char *buf = NULL;
 
@@ -56,6 +73,16 @@ static char *encapsInt(const unsigned int val) {
 }
 
 
+/**
+ * Parses any XML input document into a sqldata XML format which can be used by pgsql_INSERT().
+ * The transformation must be defined in the input XSLT template.
+ *
+ * @param xslt      XSLT template defining the data transformation
+ * @param indata_d  Input XML data to transform to a sqldata XML document
+ * @param params    Parameters to be sent to the XSLT parser
+ *
+ * @return Returns a well formed sqldata XML document on success, otherwise NULL is returned.
+ */
 xmlDoc *parseToSQLdata(xsltStylesheet *xslt, xmlDoc *indata_d, parseParams *params) {
         xmlDoc *result_d = NULL;
         char *xsltparams[10];
@@ -112,7 +139,17 @@ xmlDoc *parseToSQLdata(xsltStylesheet *xslt, xmlDoc *indata_d, parseParams *para
 }
 
 
-char *sqldataValueHash(xmlNode *sql_n) {
+/**
+ * Internal xmlparser function.   Extracts the value from a '//sqldata/records/record/value'
+ * node and hashes the value if the 'hash' attribute is set.  Otherwise the value is extracted
+ * from the node directly.  This function is only used by sqldataExtractContent().
+ *
+ * @param sql_n sqldata values node containing the value to extract.
+ *
+ * @return Returns a pointer to a new buffer containing the value on success, otherwise NULL.
+ *         This memory buffer must be free'd after usage.
+ */
+static inline char *sqldataValueHash(xmlNode *sql_n) {
 	const char *hash = NULL;
 	SHA1Context shactx;
 	uint8_t shahash[SHA1_HASH_SIZE];
@@ -150,6 +187,15 @@ char *sqldataValueHash(xmlNode *sql_n) {
 }
 
 
+/**
+ * Extract the content of a '//sqldata/records/record/value' node.  It will consider
+ * both the 'hash' and 'type' attributes of the 'value' tag.
+ *
+ * @param sql_n  Pointer to a value node of a sqldata XML document.
+ *
+ * @return Returns a pointer to a new memory buffer containing the value as a string.
+ *         On errors, NULL is returned.  This memory buffer must be free'd after usage.
+ */
 char *sqldataExtractContent(xmlNode *sql_n) {
 	const char *valtype = xmlGetAttrValue(sql_n->properties, "type");
 
@@ -172,6 +218,16 @@ char *sqldataExtractContent(xmlNode *sql_n) {
 }
 
 
+/**
+ * Return the 'fid' value of a given field in an sqldata XML document.
+ *
+ * @param sql_n  Pointer to the root xmlNode element of a sqldata XML document
+ * @param fname  String containing the field name to look up
+ *
+ * @return Returns a value >= 0 on success, containing the 'fid' value of the field.  Otherwise
+ *         a value < 0 is returned.  -1 if the field is not found or -2 if there are some problems
+ *         with the XML document.
+ */
 int sqldataGetFid(xmlNode *sql_n, const char *fname) {
 	xmlNode *f_n = NULL;
 
@@ -206,6 +262,17 @@ int sqldataGetFid(xmlNode *sql_n, const char *fname) {
 }
 
 
+/**
+ * Retrieves the value of a particular field in an sqldata XML document.
+ *
+ * @param sqld   pointer to an sqldata XML document.
+ * @param fname  String containing the field name to extract the value of.
+ * @param recid  Integer containing the record ID of the record to extract the value.  This starts
+ *               on 0.
+ *
+ * @return Returns a pointer to a new memory buffer containing the extracted value.  On errors or if
+ *         recid is higher than available records, NULL is returned.
+ */
 char *sqldataGetValue(xmlDoc *sqld, const char *fname, int recid ) {
 	xmlNode *r_n = NULL;
 	int fid = -3, rc = 0;
@@ -260,6 +327,21 @@ char *sqldataGetValue(xmlDoc *sqld, const char *fname, int recid ) {
 }
 
 
+/**
+ * Helper function to parse an sqldata XML document for the systems_hostname table.  In addition
+ * it will also return two strings containing hostname and ipaddress of the host.
+ *
+ * @param xslt       Pointer to an xmlparser.xml XSLT template
+ * @param summaryxml rteval XML report document
+ * @param syskey     Integer containing the syskey value corresponding to this host
+ * @param hostname   Return pointer for where the hostname will be saved.
+ * @param ipaddr     Return pointer for where the IP address will be saved.
+ *
+ * @return Returns a sqldata XML document on success.  In this case the hostname and ipaddr will point
+ *         at memory buffers containing hostname and ipaddress.  These values must be free'd after usage.
+ *         On errors the function will return NULL and hostname and ipaddr will not have been touched
+ *         at all.
+ */
 xmlDoc *sqldataGetHostInfo(xsltStylesheet *xslt, xmlDoc *summaryxml,
 			   int syskey, char **hostname, char **ipaddr)
 {
diff --git a/server/parser/xmlparser.h b/server/parser/xmlparser.h
index 147e5f3..096f425 100644
--- a/server/parser/xmlparser.h
+++ b/server/parser/xmlparser.h
@@ -29,7 +29,6 @@ typedef struct {
 } parseParams;
 
 xmlDoc *parseToSQLdata(xsltStylesheet *xslt, xmlDoc *indata_d, parseParams *params);
-char *sqldataValueHash(xmlNode *sql_n);
 char *sqldataExtractContent(xmlNode *sql_n);
 int sqldataGetFid(xmlNode *sqld, const char *fname);
 char *sqldataGetValue(xmlDoc *sqld, const char *fname, int recid);