[GNUnet-SVN] [libfints] branch master updated: comments

[gnunet]

This is an automated email from the git hooks/post-receive script.

marcello pushed a commit to branch master
in repository libfints.

The following commit(s) were added to refs/heads/master by this push:
     new 05a4755  comments
05a4755 is described below

commit 05a47559a2559b5c2433445e043f2d1af1614484
Author: Marcello Stanisci <address@hidden>
AuthorDate: Tue Oct 9 17:04:46 2018 +0200

    comments
---
 src/libebics.c |   7 +-
 src/xmlproto.c | 237 +++++++++++++++++++++++++++++++++++++--------------------
 src/xmlproto.h |  99 +++++++++++++++++++++---
 3 files changed, 248 insertions(+), 95 deletions(-)

diff --git a/src/libebics.c b/src/libebics.c
index 20b234b..1ec6572 100644
--- a/src/libebics.c
+++ b/src/libebics.c
@@ -411,15 +411,16 @@ EBICS_generate_message_ini (struct EBICS_genex_document 
*document,
 {
 
   struct EBICS_MSG_Spec spec[] = {
+
     /* Notably, it sets the HostID in the request document.  */
     EBICS_MSG_op_subcommand (EBICS_build_header_ebicsUnsecuredRequest,
-                             headerArgs,
+                             headerArgs, // has _another_ document in it, and 
message_dump.c does define it.
                              NULL),
 
     /* Set a bunch of nodes (mostly strings) taking values from 'iniArgs'.  */
     EBICS_MSG_op_subcommand (EBICS_build_content_ini,
-                             iniArgs, // has _another_ document in it
-                             iniArgs->document), // out
+                             iniArgs, // has _another_ document in it, and 
message_dump.c does define it.
+                             iniArgs->document), // out, but ignored
     EBICS_MSG_op_clean (),
     EBICS_MSG_op_end ()
   };
diff --git a/src/xmlproto.c b/src/xmlproto.c
index 0953754..1e45878 100644
--- a/src/xmlproto.c
+++ b/src/xmlproto.c
@@ -67,11 +67,10 @@ EBICS_MSG_op_select_choice (const char *xpath, const 
uint8_t choice)
 struct EBICS_MSG_Spec
 EBICS_MSG_op_unique_choice (const char *xpath) 
 {
-  struct EBICS_MSG_Spec result = 
-    {
+  struct EBICS_MSG_Spec result = {
       .operation = EBICS_MSG_OP_UNIQUE_CHOICE, 
-      .xpath = xpath, 
-    };
+      .xpath = xpath,
+  };
   return result;
 };
 
@@ -475,9 +474,12 @@ static void
 process_unique (const struct EBICS_MSG_Spec *operation,
                 struct EBICS_genex_document *document)
 {
+
   xmlXPathContextPtr xpathCtxPtr = document->xpath;
   xmlDocPtr doc = document->document;
-  xmlXPathObjectPtr xpathObjPtr = xmlXPathEvalExpression(BAD_CAST 
operation->xpath, xpathCtxPtr);
+  xmlXPathObjectPtr xpathObjPtr = xmlXPathEvalExpression
+    (BAD_CAST operation->xpath,
+     xpathCtxPtr);
   assert(NULL != xpathObjPtr);
   assert(NULL != xpathObjPtr->nodesetval);
   xmlNodeSetPtr nodeset = xpathObjPtr->nodesetval;
@@ -672,165 +674,234 @@ process_date (const struct EBICS_MSG_Spec *operation,
   xmlXPathFreeObject(xpathObjPtr);
 }
 
-/** Parse a set attribute operation.
+/**
+ * Parse a set attribute operation.
+ *
+ * @param operation the operation to run
+ * @param document the output document.
  */
 static void
 process_attribute_set (const struct EBICS_MSG_Spec *operation,
                        struct EBICS_genex_document *document)
 {
-  xmlXPathContextPtr xpathCtxPtr = document->xpath;
-  xmlDocPtr doc = document->document;
+
   int i;
   xmlNodePtr node;
+
+  xmlXPathContextPtr xpathCtxPtr = document->xpath;
+  xmlDocPtr doc = document->document;
   xmlChar *text = operation->data.attribute.value;
   xmlChar *name = operation->data.attribute.name;
-  xmlXPathObjectPtr xpathObjPtr = xmlXPathEvalExpression(BAD_CAST 
operation->xpath, xpathCtxPtr);
-  assert(NULL != xpathObjPtr);
-  assert(NULL != xpathObjPtr->nodesetval);
+  xmlXPathObjectPtr xpathObjPtr = xmlXPathEvalExpression
+    (BAD_CAST operation->xpath,
+     xpathCtxPtr);
+  assert (NULL != xpathObjPtr);
+  assert (NULL != xpathObjPtr->nodesetval);
   xmlNodeSetPtr nodeset = xpathObjPtr->nodesetval;
 
-  LOG(EBICS_LOGLEVEL_INFO,"process_attribute_set: \
-              xpath: %s Xpathresult: %p, \
-              nodeset: %p, nodeNr: %u", 
-              operation->xpath, xpathObjPtr, 
-              nodeset, nodeset->nodeNr);
+  LOG (EBICS_LOGLEVEL_INFO,
+       "process_attribute_set: \
+       xpath: %s Xpathresult: %p, \
+       nodeset: %p, nodeNr: %u", 
+       operation->xpath,
+       xpathObjPtr, 
+       nodeset,
+       nodeset->nodeNr);
+
   for (i = (nodeset->nodeNr); i > 0; i--)
   {
-    LOG(EBICS_LOGLEVEL_INFO,"process_attribute_set: setting text: %s",text);
+    LOG (EBICS_LOGLEVEL_INFO,
+         "process_attribute_set: setting text: %s",
+         text);
     node = nodeset->nodeTab[i-1];
     xmlNodeSetContent(node, text);
     remove_opt_attribute(node, doc);
 
   }
-  xmlXPathFreeObject(xpathObjPtr);
-  free(name);
-  free(text);
+  xmlXPathFreeObject (xpathObjPtr);
+  free (name);
+  free (text);
 }
 
+
+/**
+ * Delete a (XML) attribute from the document.
+ *
+ * @param operation the delete-attribute operation
+ * @param document the output document
+ */
 static void
 process_attribute_del (const struct EBICS_MSG_Spec *operation,
                        struct EBICS_genex_document *document)
 {
-  xmlXPathContextPtr xpathCtxPtr = document->xpath;
   int i;
   xmlNodePtr node;
-  xmlXPathObjectPtr xpathObjPtr = xmlXPathEvalExpression(BAD_CAST 
operation->xpath, xpathCtxPtr);
-  assert(NULL != xpathObjPtr);
-  assert(NULL != xpathObjPtr->nodesetval);
+  xmlXPathContextPtr xpathCtxPtr = document->xpath;
+
+  xmlXPathObjectPtr xpathObjPtr = xmlXPathEvalExpression
+    (BAD_CAST operation->xpath,
+     xpathCtxPtr);
+  assert (NULL != xpathObjPtr);
+  assert (NULL != xpathObjPtr->nodesetval);
   xmlNodeSetPtr nodeset = xpathObjPtr->nodesetval;
 
-  LOG(EBICS_LOGLEVEL_INFO,"process_attribute_del: \
-              xpath: %s Xpathresult: %p, \
-              nodeset: %p, nodeNr: %u", 
-              operation->xpath, xpathObjPtr, 
-              nodeset, nodeset->nodeNr);
+  LOG (EBICS_LOGLEVEL_INFO,
+       "process_attribute_del: \
+       xpath: %s Xpathresult: %p, \
+       nodeset: %p, nodeNr: %u", 
+       operation->xpath,
+       xpathObjPtr, 
+       nodeset,
+       nodeset->nodeNr);
+
   for (i = (nodeset->nodeNr); i > 0; i--)
   {
     node = nodeset->nodeTab[i-1];
-    //xmlNodeSetContent(node, text);
-    //xmlUnsetProp(xmlNodePtr node, const xmlChar * name)
-    xmlUnlinkNode(node);
-    xmlFreeNode(node);
+    // xmlNodeSetContent (node, text);
+    // xmlUnsetProp (xmlNodePtr node, const xmlChar * name)
+    xmlUnlinkNode (node);
+    xmlFreeNode (node);
     nodeset->nodeTab[i-1] = NULL;
   }
-  xmlXPathFreeObject(xpathObjPtr);
+  xmlXPathFreeObject (xpathObjPtr);
 }
 
+
+/**
+ * Add a (XML) attribute to the document.
+ *
+ * @param operation the operation to run (contains the attribute
+ *        to add)
+ * @param document the output document
+ */
 static void
 process_attribute_add (const struct EBICS_MSG_Spec *operation,
                        struct EBICS_genex_document *document)
 {
-  xmlXPathContextPtr xpathCtxPtr = document->xpath;
+
   int i;
   xmlNodePtr node;
+  xmlXPathContextPtr xpathCtxPtr = document->xpath;
+
   xmlChar *text = operation->data.attribute.value;
   xmlChar *name = operation->data.attribute.name;
-  xmlXPathObjectPtr xpathObjPtr = xmlXPathEvalExpression(BAD_CAST 
operation->xpath, xpathCtxPtr);
-  assert(NULL != xpathObjPtr);
-  assert(NULL != xpathObjPtr->nodesetval);
+  xmlXPathObjectPtr xpathObjPtr = xmlXPathEvalExpression
+    (BAD_CAST operation->xpath,
+     xpathCtxPtr);
+  assert (NULL != xpathObjPtr);
+  assert (NULL != xpathObjPtr->nodesetval);
   xmlNodeSetPtr nodeset = xpathObjPtr->nodesetval;
 
-  LOG(EBICS_LOGLEVEL_INFO,"process_attribute_set: \
-              xpath: %s Xpathresult: %p, \
-              nodeset: %p, nodeNr: %u", 
-              operation->xpath, xpathObjPtr, 
-              nodeset, nodeset->nodeNr);
+  LOG (EBICS_LOGLEVEL_INFO,
+       "process_attribute_set: \
+       xpath: %s Xpathresult: %p, \
+       nodeset: %p, nodeNr: %u", 
+       operation->xpath,
+       xpathObjPtr, 
+       nodeset,
+       nodeset->nodeNr);
+
   for (i = (nodeset->nodeNr); i > 0; i--)
   {
     node = nodeset->nodeTab[i-1];
-    //xmlNodeSetContent(node, text);
-    //xmlUnsetProp(xmlNodePtr node, const xmlChar * name)
-    xmlUnlinkNode(node);
-    xmlFreeNode(node);
+    // xmlNodeSetContent (node, text);
+    // xmlUnsetProp (xmlNodePtr node, const xmlChar * name)
+    xmlUnlinkNode (node);
+    xmlFreeNode (node);
     nodeset->nodeTab[i-1] = NULL;
   }
-  xmlXPathFreeObject(xpathObjPtr);
-  free(name);
-  free(text);
+  xmlXPathFreeObject (xpathObjPtr);
+  free (name);
+  free (text);
 }
 
-/** Parse a add node operation.
+/**
+ * Implement a add node operation.
+ *
+ * @param operation the operation to run (contains the new node)
+ * @param document the output document
  */
 static void
 process_add_node (const struct EBICS_MSG_Spec *operation,
                   struct EBICS_genex_document *document)
 {
-  xmlXPathContextPtr xpathCtxPtr = document->xpath;
   int i;
   xmlNodePtr node;
-  xmlXPathObjectPtr xpathObjPtr = xmlXPathEvalExpression(BAD_CAST 
operation->xpath, xpathCtxPtr);
-  assert(NULL != xpathObjPtr);
-  assert(NULL != xpathObjPtr->nodesetval);
+
+  xmlXPathContextPtr xpathCtxPtr = document->xpath;
+  xmlXPathObjectPtr xpathObjPtr = xmlXPathEvalExpression
+    (BAD_CAST operation->xpath,
+     xpathCtxPtr);
+
+  assert (NULL != xpathObjPtr);
+  assert (NULL != xpathObjPtr->nodesetval);
   xmlNodeSetPtr nodeset = xpathObjPtr->nodesetval;
 
-  LOG(EBICS_LOGLEVEL_INFO,"add_node: \
-              xpath: %s Xpathresult: %p, \
-              nodeset: %p, nodeNr: %u", 
-              operation->xpath, xpathObjPtr, 
-              nodeset, nodeset->nodeNr);
+  LOG (EBICS_LOGLEVEL_INFO,
+       "add_node: xpath: %s Xpathresult: %p, \
+       nodeset: %p, nodeNr: %u", 
+       operation->xpath,
+       xpathObjPtr, 
+       nodeset,
+       nodeset->nodeNr);
 
   for (i = (nodeset->nodeNr); i > 0; i--)
   {
     node = nodeset->nodeTab[i-1];
-    xmlNodePtr new = xmlCopyNodeList(operation->data.add_node.node);
-    assert(NULL != new);
-    xmlNodePtr res = xmlAddChild(node, new);
-    assert(NULL != res);
-    assert(res == new);
+    xmlNodePtr new = xmlCopyNodeList
+      (operation->data.add_node.node);
+    assert (NULL != new);
+    xmlNodePtr res = xmlAddChild (node, new);
+    assert (NULL != res);
+    assert (res == new);
   }
-  xmlXPathFreeObject(xpathObjPtr);
+  xmlXPathFreeObject (xpathObjPtr);
 }
 
-/** Parse a delete node operation.
+/**
+ * Implement the delete operation.
+ *
+ * @param operation the delete operation to run
+ * @param document output
  */
 static void
 process_del_node (const struct EBICS_MSG_Spec *operation,
                   struct EBICS_genex_document *document)
 {
-  xmlXPathContextPtr xpathCtxPtr = document->xpath;
+
   int i;
   xmlNodePtr node;
-  xmlXPathObjectPtr xpathObjPtr = xmlXPathEvalExpression(BAD_CAST 
operation->xpath, xpathCtxPtr);
+  xmlXPathContextPtr xpathCtxPtr = document->xpath;
+  xmlXPathObjectPtr xpathObjPtr = xmlXPathEvalExpression
+    (BAD_CAST operation->xpath,
+     xpathCtxPtr);
+
   assert(NULL != xpathObjPtr);
   assert(NULL != xpathObjPtr->nodesetval);
   xmlNodeSetPtr nodeset = xpathObjPtr->nodesetval;
 
-  LOG(EBICS_LOGLEVEL_INFO,"del_node: \
-              xpath: %s Xpathresult: %p, \
-              nodeset: %p, nodeNr: %u", 
-              operation->xpath, xpathObjPtr, 
-              nodeset, nodeset->nodeNr);
+  LOG(EBICS_LOGLEVEL_INFO,
+      "del_node: xpath: %s Xpathresult: %p, \
+      nodeset: %p, nodeNr: %u", 
+      operation->xpath,
+      xpathObjPtr, 
+      nodeset, nodeset->nodeNr);
+
+  LOG (EBICS_LOGLEVEL_INFO,
+       "del_nodes: Number of Nodes found: %d\n",
+       nodeset->nodeNr);
 
-  LOG(EBICS_LOGLEVEL_INFO,"del_nodes: Number of Nodes found: 
%d",nodeset->nodeNr);
   for (i = (nodeset->nodeNr); i > 0; i--)
   {
     node = nodeset->nodeTab[i-1];
-    LOG(EBICS_LOGLEVEL_INFO,"\tFound: %s", node->name);
-    xmlUnlinkNode(node);
-    xmlFreeNode(node);
+    LOG (EBICS_LOGLEVEL_INFO,
+         "\tFound: %s",
+         node->name);
+    xmlUnlinkNode (node);
+    xmlFreeNode (node);
     nodeset->nodeTab[i-1] = NULL;
   }
-  xmlXPathFreeObject(xpathObjPtr);
+  xmlXPathFreeObject (xpathObjPtr);
 }
 
 /**
@@ -857,6 +928,9 @@ process_subcommand (const struct EBICS_MSG_Spec *operation,
 
 /**
  * Parse a end operation.
+ *
+ * @param operation operation object.
+ * @param document output document.
  */
 static void
 process_end (const struct EBICS_MSG_Spec *operation,
@@ -868,10 +942,11 @@ process_end (const struct EBICS_MSG_Spec *operation,
 
 /**
  * Parse document according to given command specification.
- * Each element of the operation list is called with the appropriate parser 
function.
+ * Each element of the operation list is called with the
+ * appropriate parser function.
  *
  * @param ops Array containing MSG_spec structs.
- * @param doc Pointer to the base document
+ * @param document Pointer to the base document
  */
 void
 EBICS_MSG_parse_spec (const struct EBICS_MSG_Spec *ops,
diff --git a/src/xmlproto.h b/src/xmlproto.h
index ac4952d..68df8c7 100644
--- a/src/xmlproto.h
+++ b/src/xmlproto.h
@@ -129,90 +129,167 @@ struct EBICS_MSG_Spec
    * Format of the operation
    */
   enum EBICS_MSG_Operations operation;
+
+  /**
+   * (X)Path to the target element.
+   */
   const char *xpath;
+
   union
   {
-    /* Select single choice */
     struct
     {
+
+      /** 
+       * Every choice element is assigned
+       * a index number; this values indicates
+       * _which_ choice index is to be kept.
+       * Other elements will be discarded from
+       * the tree.
+       *
+       * XXX: are the index assigned in a
+       * deterministic manner?  If not, this
+       * value is bug-prone.
+       */
       uint8_t choice;
+
     } select_choice;
 
-    /* Select unique choice */
     struct
     {
+      /**
+       * Never used; purge?
+       */
     } select_unique;
 
-    /* Add a node */
     struct
     {
+
+      /**
+       * Node to add to the tree.
+       */
       xmlNodePtr node;
+
     } add_node;
 
-    /* Remove a node */
     struct
     {
+
+      /**
+       * Node to delete.  XXX why need the
+       * pointer to the node?  Isn't it enough
+       * to specify the XPath to the node to delete?
+       * NOTE: this field looks UNUSED, and so might
+       * better be removed from here.
+       */
       xmlNodePtr node;
+
     } del_node;
 
-    /* Set a flag */
     struct
     {
+
+      /**
+       * Flag to assign to the target element.
+       */
       bool value;
+
     } set_flag;
 
-    /* Set text */
     struct
     {
+
+      /**
+       * Test to assign to the target element.
+       */
       xmlChar *value;
+
     } set_string;
 
-    /* Set uint */
     struct
     {
+
+      /**
+       * Unsigned integer to assign to the target element.
+       */
       uint64_t value;
+
     } set_uint;
 
     struct
     {
+
+      /**
+       * Date to assign to the target element.
+       */
       struct EBICS_Date date;
+
     } set_date;
 
     /* Set int */
     struct
     {
+
+      /**
+       * Value to assign to the target element.
+       */
       int64_t value;
+
     } set_int;
 
     /* Set attribute */
     struct
     {
+
+      /**
+       * Name of the attribute.
+       */
       xmlChar *name;
+
+      /**
+       * Value for the named attribute.
+       */
       xmlChar *value;
+
     } attribute;
 
-    /* Execute subcommand */
     struct
     {
+      /**
+       * Callback function. 
+       */
       EBICS_MSG_subcommand_fn function;
+
+      /**
+       * Target document.
+       */
       struct EBICS_genex_document *target;
+
+      /**
+       * General purpose closure for the callaback.
+       */
       void *cls;
+
     } subcommand;
+
   } data;
 };
 
 /**
- * Select a choice from the tree.
  * Selects a choice from the tree, unlinks the unselected choices 
  * and relinks the content to the choices parent node.
  *
- * @param xpath XPath expression that specifies _one_ CHOCIES element.
+ * @param xpath XPath expression that specifies _one_ CHOICES element.
  * @param choice Index of the CHOICE to select.
+ * @return the operation to run.
  */
-
 struct EBICS_MSG_Spec
 EBICS_MSG_op_select_choice (const char *xpath, const uint8_t choice);
 
+
+/** 
+ *
+ */
 struct EBICS_MSG_Spec
 EBICS_MSG_op_unique_choice (const char *xpath);
 

-- 
To stop receiving notification emails like this one, please contact
address@hidden