From 4dbb674d486f22e07d20f1a818ee8b66691d1bd8 Mon Sep 17 00:00:00 2001 From: David Sommerseth Date: Mon, 12 Oct 2009 20:37:27 +0200 Subject: Added doxygen comments for xmlparser.[ch] and pgsql.c --- server/parser/pgsql.c | 105 ++++++++++++++++++++++++++++++++++++++++++++++ server/parser/xmlparser.c | 84 ++++++++++++++++++++++++++++++++++++- server/parser/xmlparser.h | 1 - 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 +/** + * 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 + * + * + * {field name} + * ... + * ... + * {field name 'n'} + * + * + * + * {value for field 'fid' + * ... + * ... + * {value for field 'fid_n' + * + * ... + * ... + * ... + * + * + * @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 +/** + * 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); -- cgit