[taler-taler-mdb] 01/02: commented code

[gnunet]

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

marco-boss pushed a commit to branch master
in repository taler-mdb.

commit 57de4d50cb0dfdc391386a7383a82dcfb47fbb38
Author: Boss Marco <address@hidden>
AuthorDate: Tue Dec 10 16:28:46 2019 +0100

    commented code
---
 src/main.c | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 65 insertions(+), 11 deletions(-)

diff --git a/src/main.c b/src/main.c
index e9ddb5a..29e9acc 100644
--- a/src/main.c
+++ b/src/main.c
@@ -24,7 +24,7 @@ along with
 * @author Dominik Hofer
 *
 * TODO:
-* - comment code (Boss)
+* - comment code mdb incl. doxygen struct members (hofer)
 */
 #include "config.h"
 #include <stdio.h>
@@ -552,8 +552,19 @@ static char *framebuffer_device_filename;
  */
 static char *framebuffer_backlight_filename;
 
+/**
+ * Global option '-i' to invert backlight on/off values
+ */
 static int backlight_invert;
+
+/**
+ * Standard backlight on value
+ */
 static char backlight_on = '1';
+
+/**
+ * Standard backlight off value
+ */
 static char backlight_off = '0';
 
 /**
@@ -689,12 +700,13 @@ show_qrcode (const char *uri)
     return;
   }
 
-  /* +8 for 4-pixels border */
+  /* set QR-code border */
   size = GNUNET_MIN (qrDisplay.var_info.xres,
                      qrDisplay.var_info.yres);
-  unsigned int nwidth = qrc->width + 8; /* 4 pixel border */
+  unsigned int nwidth = qrc->width + 8; /* +8 for 4 pixel border */
   xOff = 4 * size / nwidth;
   yOff = 4 * size / nwidth;
+  /* calculate offset to show the code centered */
   if (qrDisplay.var_info.xres < qrDisplay.var_info.yres)
     yOff += (qrDisplay.var_info.yres - qrDisplay.var_info.xres) / 2;
   else
@@ -708,6 +720,7 @@ show_qrcode (const char *uri)
       if ( (xoff >= (unsigned) qrc->width) ||
            (yoff >= (unsigned) qrc->width) )
         continue;
+      /* set the pixels in the display memory */
       qrDisplay.memory[(y + yOff) * qrDisplay.var_info.xres + (x + xOff)] =
         (0 == (qrc->data[off] & 1)) ? 0xFFFF : 0x0000;
     }
@@ -715,11 +728,11 @@ show_qrcode (const char *uri)
   QRcode_free (qrc);
   QRinput_free (qri);
 
+  /* turn on backlight if supported */
   if (0 < qrDisplay.backlightfd)
     (void) write (qrDisplay.backlightfd, &backlight_on, 1);
 }
 
-
 #endif
 
 
@@ -729,6 +742,7 @@ run_mdb_event_loop (void);
 
 /**
  * @brief Cleanup all the data when a order has succeeded or got cancelled
+ *
  * @param pa the payment activity to clean up
  */
 static void
@@ -873,13 +887,14 @@ shutdown_task (void *cls)
       GNUNET_log (GNUNET_ERROR_TYPE_WARNING,
                   "failed to reset originial display state\n");
     }
-    /* close device */
+    /* close the device */
     close (qrDisplay.devicefd);
     qrDisplay.devicefd = -1;
     if (0 < qrDisplay.backlightfd)
       close (qrDisplay.backlightfd);
     qrDisplay.backlightfd = -1;
   }
+  /* free the allocated productes read from config file */
   if (NULL != products)
   {
     for (unsigned int i = 0; i < products_length; i++)
@@ -914,13 +929,16 @@ static void
 wallet_transmit_uri (void *cls)
 {
   struct PaymentActivity *pa = cls;
+  /* response array for APDU response status word */
   uint8_t response[] = { 0x00, 0x00 };
   size_t slen = strlen (pa->taler_pay_uri);
   uint8_t message[sizeof (put_data) + slen];
 
   pa->delay_task = NULL;
+  /* append the pay uri to the put data command */
   memcpy (message, put_data, sizeof (put_data));
   memcpy (&message[sizeof (put_data)], pa->taler_pay_uri, slen);
+  /* send the put data command via nfc */
   GNUNET_log (GNUNET_ERROR_TYPE_INFO,
               "Sending 'PUT DATA' command for `%s' to wallet\n",
               pa->taler_pay_uri);
@@ -937,6 +955,7 @@ wallet_transmit_uri (void *cls)
                                          pa);
     return;
   }
+  /* check if the transmission succeeded */
   if (0 != memcmp (response,
                    APDU_SUCCESS,
                    sizeof (response)))
@@ -953,6 +972,10 @@ wallet_transmit_uri (void *cls)
               "'PUT DATA' command sent successfully via NFC\n");
   pa->wallet_has_uri = GNUNET_YES;
   /* FIXME: or just offer Internet service here? */
+
+  /* transmit the uri again later, there can be many external failures,
+     for example the taler wallet app was not opened and thus did not receive
+     the data */
   pa->delay_task = GNUNET_SCHEDULER_add_delayed (MAX_HTTP_RETRY_FREQ,
                                                  &wallet_transmit_uri,
                                                  pa);
@@ -960,7 +983,9 @@ wallet_transmit_uri (void *cls)
 
 
 /**
- * @brief Select the taler wallet app via NFC
+ * @brief Select the taler wallet app via NFC on the target selected with
+ * @e connect_target()
+ * (check if it is installed on the smartphone)
  *
  * @param cls closure
  */
@@ -968,13 +993,16 @@ static void
 wallet_select_aid (void *cls)
 {
   struct PaymentActivity *pa = cls;
+  /* response array for APDU response status word */
   uint8_t response[] = { 0x00, 0x00 };
   uint8_t message[sizeof(select_file) + sizeof(taler_aid)];
 
   pa->task = NULL;
+  /* append the taler wallet aid to the select file command */
   memcpy (message, select_file, sizeof (select_file));
   memcpy (&message[sizeof (select_file)], taler_aid, sizeof (taler_aid));
 
+  /* send the select file command via nfc */
   GNUNET_log (GNUNET_ERROR_TYPE_INFO,
               "Trying to find Taler wallet on NFC\n");
   if (0 > nfc_initiator_transceive_bytes (pa->pnd,
@@ -990,6 +1018,7 @@ wallet_select_aid (void *cls)
                                          pa);
     return;
   }
+  /* check if the transmission succeeded */
   if (0 == memcmp (response,
                    APDU_SUCCESS,
                    sizeof (response)))
@@ -1000,6 +1029,7 @@ wallet_select_aid (void *cls)
                                                pa);
     return;
   }
+  /* if the transmission was not successful chack if the app is available at 
all */
   if (0 == memcmp (response,
                    APDU_NOT_FOUND,
                    sizeof (response)))
@@ -1010,10 +1040,12 @@ wallet_select_aid (void *cls)
                                          pa);
     return;
   }
+  /* If the upper cases did not match, there was an unknown APDU status 
returned */
   GNUNET_log (GNUNET_ERROR_TYPE_WARNING,
               "AID selection failure, return code: %x%x, trying to find 
another NFC client\n",
               response[0],
               response[1]);
+  /* start the selection again */
   pa->task = GNUNET_SCHEDULER_add_delayed (NFC_FAILURE_RETRY_FREQ,
                                            &connect_target,
                                            pa);
@@ -1029,13 +1061,16 @@ static void
 connect_target (void *cls)
 {
   struct PaymentActivity *pa = cls;
+  /* nfc modulation used */
   const nfc_modulation nmMifare = {
     .nmt = NMT_ISO14443A,
     .nbr = NBR_212,
   };
 
   pa->task = NULL;
+  /* set the uid len to zero (maybe it is still set from earlier selections) */
   pa->nt.nti.nai.szUidLen = 0;
+  /* poll for a fitting nfc target (we use the shortest time possible to not 
block the scheduler) */
   GNUNET_log (GNUNET_ERROR_TYPE_INFO,
               "Trying to find NFC client\n");
   if (0 > nfc_initiator_poll_target (pa->pnd,
@@ -1048,6 +1083,7 @@ connect_target (void *cls)
     GNUNET_log (GNUNET_ERROR_TYPE_INFO,
                 "Failed to connect to NFC target\n");
   }
+  /* if the uid lenght are out of bound abort */
   else if ( (pa->nt.nti.nai.szUidLen > UID_LEN_UPPER) ||
             (pa->nt.nti.nai.szUidLen < UID_LEN_LOWER) )
   {
@@ -1056,12 +1092,15 @@ connect_target (void *cls)
   }
   else
   {
+    /* the target was successfully selected,
+       now we have to check if the taler wallet is installed on it */
     GNUNET_log (GNUNET_ERROR_TYPE_INFO,
                 "Found NFC client\n");
     pa->task = GNUNET_SCHEDULER_add_now (&wallet_select_aid,
                                          pa);
     return;
   }
+  /* if no target was found try again */
   pa->task = GNUNET_SCHEDULER_add_delayed (NFC_FAILURE_RETRY_FREQ,
                                            &connect_target,
                                            pa);
@@ -1079,6 +1118,7 @@ open_nfc_reader (void *cls)
   struct PaymentActivity *pa = cls;
 
   pa->task = NULL;
+  /* open the nfc reader via libnfc's open */
   GNUNET_log (GNUNET_ERROR_TYPE_INFO,
               "Trying to open NFC device\n");
   pa->pnd = nfc_open (context, NULL);
@@ -1091,6 +1131,7 @@ open_nfc_reader (void *cls)
                                              pa);
     return;
   }
+  /* initialize the reader as initiator */
   if (0 > nfc_initiator_init (pa->pnd))
   {
     GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
@@ -1105,6 +1146,7 @@ open_nfc_reader (void *cls)
               "NFC in operation %s / %s\n",
               nfc_device_get_name (pa->pnd),
               nfc_device_get_connstring (pa->pnd));
+  /* the nfc reader was opened successfully, now try to find a mobile device 
as a target */
   pa->task = GNUNET_SCHEDULER_add_now (&connect_target,
                                        pa);
 }
@@ -1319,6 +1361,7 @@ launch_payment (const struct Product *product)
   }
   pa = GNUNET_new (struct PaymentActivity);
   pa->amount = product->price;
+  /* put the order on the merchant's backend */
   pa->po = TALER_MERCHANT_order_put (ctx,
                                      backendBaseUrl,
                                      orderReq,
@@ -2051,7 +2094,7 @@ run_mdb_event_loop ()
 /**
  * @brief Read the products from the configuration file
  *
- * @param cls closure
+ * @param cls closure in this case the name of the configuration file to read 
from
  * @param section section of the config file to read from
  */
 static void
@@ -2061,10 +2104,12 @@ read_products (void *cls,
   struct Product tmpProduct;
   char *tmpKey;
 
+  /* if the current section is not a product skip it */
   if (0 != strncmp (section,
                     "product-",
                     strlen ("product-")))
     return;
+  /* the current section is a product, parse its specifications and store it 
in a temporary product */
   if (GNUNET_OK !=
       GNUNET_CONFIGURATION_get_value_string (cls,
                                              section,
@@ -2124,6 +2169,7 @@ read_products (void *cls,
     GNUNET_free (tmpProduct.description);
     return;
   }
+  /* append the temporary product to the existing products */
   GNUNET_array_append (products,
                        products_length,
                        tmpProduct);
@@ -2218,6 +2264,7 @@ run (void *cls,
   (void) args;
   (void) cfgfile;
 
+  /* parse the configuration file */
   if (GNUNET_OK !=
       GNUNET_CONFIGURATION_get_value_string (cfg,
                                              "taler",
@@ -2230,6 +2277,7 @@ run (void *cls,
     global_ret = EXIT_FAILURE;
     return;
   }
+  /* parse the devices, if no config entry is found, a standard is used */
   if (GNUNET_OK !=
       GNUNET_CONFIGURATION_get_value_filename (cfg,
                                                "taler-mdb",
@@ -2264,6 +2312,7 @@ run (void *cls,
     framebuffer_backlight_filename = GNUNET_strdup (
       "/sys/class/backlight/soc:backlight/brightness");
   }
+  /* parse the taler configurations */
   if (GNUNET_OK !=
       GNUNET_CONFIGURATION_get_value_string (cfg,
                                              "taler-mdb",
@@ -2290,6 +2339,7 @@ run (void *cls,
       global_ret = EXIT_FAILURE;
       return;
     }
+    /* concat the authorization e.g. Authorization: ApiKey sandbox */
     GNUNET_asprintf (&authorization,
                      "%s: %s",
                      MHD_HTTP_HEADER_AUTHORIZATION,
@@ -2320,6 +2370,7 @@ run (void *cls,
     global_ret = EXIT_FAILURE;
     return;
   }
+  /* parse the products */
   GNUNET_CONFIGURATION_iterate_sections (cfg,
                                          &read_products,
                                          (void *) cfg);
@@ -2402,20 +2453,20 @@ run (void *cls,
                               PROT_READ | PROT_WRITE, MAP_SHARED,
                               qrDisplay.devicefd,
                               0);
-
-    /* open backlight file to turn display backlight on and off */
-    if (0 > qrDisplay.devicefd)
+    if (0 > qrDisplay.memory)
     {
       GNUNET_log_strerror (GNUNET_ERROR_TYPE_WARNING,
                            "mmap");
       return;
     }
 
+    /* set the screen to white */
     memset (qrDisplay.memory,
             0xFF,
             qrDisplay.var_info.xres * qrDisplay.var_info.yres
             * sizeof (uint16_t));
 
+    /* open backlight file to turn display backlight on and off */
     qrDisplay.backlightfd = open (
       framebuffer_backlight_filename, O_WRONLY);
     if (0 > qrDisplay.backlightfd)
@@ -2426,11 +2477,13 @@ run (void *cls,
     }
     else
     {
+      /* if '-i' flag was set, invert the on and off values */
       if (backlight_invert)
       {
         backlight_on = '0';
         backlight_off = '1';
       }
+      /* turn off the backlight */
       (void) write (qrDisplay.backlightfd, &backlight_off, 1);
     }
   }
@@ -2506,7 +2559,9 @@ main (int argc,
       char*const*argv)
 {
   struct termios tty_opts_backup, tty_opts_raw;
+  int have_tty;
   int ret;
+
   /* the available command line options */
   struct GNUNET_GETOPT_CommandLineOption options[] = {
     GNUNET_GETOPT_option_flag ('d',
@@ -2523,7 +2578,6 @@ main (int argc,
                                &backlight_invert),
     GNUNET_GETOPT_OPTION_END
   };
-  int have_tty;
 
   if (! disable_tty)
   {

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