agent-at: Improve comments

Change-Id: Ica1479c4ccac93ff153c0e0bf79a3eab6ae882f9
Signed-off-by: José Bollo <jose.bollo@iot.bzh>

diff --git a/src/agent-at.c b/src/agent-at.c
index 02bcc6c..6a33bf6 100644 (file)
--- a/src/agent-at.c
+++ b/src/agent-at.c
@@ -24,6 +24,16 @@
 #include "data.h"
 #include "cyn.h"
 
+/**
+ * Parse the spec to extract the derived key to ask.
+ *
+ * @param spec   The specification of the derived key
+ * @param rkey   The originally requested key
+ * @param key    The derived key or NULL for computing length
+ * @param buffer The buffer that handles texts or NULL for computing length
+ * @param szbuf  The size of the buffer or 0 for computing length
+ * @return the total length of buffer used
+ */
 static
 size_t
 parse(
@@ -37,14 +47,22 @@ parse(
        const char *val;
 
        iout = 0;
-       for (ikey = 0 ; ikey < 4 ; ikey++) {
+       for (ikey = 0 ; ikey < KeyIdx_Count ; ikey++) {
                inf = iout;
                while(*spec) {
                        if (*spec == ':' && ikey < 3) {
+                               /* : is the separator of key's items */
                                spec++;
-                               break;
+                               break; /* next key */
                        }
-                       if (*spec == '%' && spec[1]) {
+                       if (!(*spec == '%' && spec[1])) {
+                               /* not a % substitution mark */
+                               if (iout < szbuf)
+                                       buffer[iout] = *spec;
+                               iout++;
+                               spec++;
+                       } else {
+                               /* what % substitution is it? */
                                switch(spec[1]) {
                                case 'c':
                                        val = rkey->client;
@@ -59,9 +77,11 @@ parse(
                                        val = rkey->permission;
                                        break;
                                default:
+                                       /* none */
                                        val = 0;
                                }
                                if (val) {
+                                       /* substitution of the value */
                                        while (*val) {
                                                if (iout < szbuf)
                                                        buffer[iout] = *val;
@@ -69,7 +89,9 @@ parse(
                                                val++;
                                        }
                                } else {
+                                       /* no substitution */
                                        if (spec[1] != ':' && spec[1] != '%') {
+                                               /* only escape % and : */
                                                if (iout < szbuf)
                                                        buffer[iout] = '%';
                                                iout++;
@@ -79,27 +101,34 @@ parse(
                                        iout++;
                                }
                                spec += 2;
-                       } else {
-                               if (iout < szbuf)
-                                       buffer[iout] = *spec;
-                               iout++;
-                               spec++;
                        }
                }
                if (inf == iout)
-                       val = 0;
+                       val = 0; /* empty key item */
                else {
+                       /* set zero ended key */
                        val = &buffer[inf];
                        if (iout < szbuf)
                                buffer[iout] = 0;
                        iout++;
                }
                if (key)
-                       ((const char**)key)[ikey] = val;
+                       key->keys[ikey] = val;
        }
        return iout;
 }
 
+/**
+ * Implementation of the AT-agent callback
+ *
+ * @param name               name of the agent (not used, should be "@")
+ * @param agent_closure      closure of the agent (not used)
+ * @param key                the original searched key
+ * @param value              the value found (string after @:)
+ * @param on_result_cb       callback that will asynchronously handle the result
+ * @param on_result_closure  closure for 'on_result_cb'
+ * @return
+ */
 static
 int
 agent_at_cb(
@@ -114,12 +143,21 @@ agent_at_cb(
        char *block;
        size_t size;
 
+       /* compute the length */
        size = parse(value, key, 0, 0, 0);
+       /* alloc the length locally */
        block = alloca(size);
+       /* initialize the derived key */
        parse(value, key, &atkey, block, size);
+       /* ask for the derived key */
        return cyn_test_async(on_result_cb, on_result_closure, &atkey);
 }
 
+/**
+ * Activate the AT-agent
+ *
+ * @return 0 in case of success of a negative value in -errno style.
+ */
 int
 agent_at_activate(
 ) {

diff --git a/src/data.h b/src/data.h
index 8bd35b3..ef387f8 100644 (file)
--- a/src/data.h
+++ b/src/data.h
@@ -31,11 +31,24 @@
 typedef struct data_key data_key_t;
 typedef struct data_value data_value_t;
 
+enum data_keyidx {
+       KeyIdx_Client,
+       KeyIdx_Session,
+       KeyIdx_User,
+       KeyIdx_Permission,
+       KeyIdx_Count
+};
+
 struct data_key {
-       const char *client;
-       const char *session;
-       const char *user;
-       const char *permission;
+       union {
+               struct {
+                       const char *client;
+                       const char *session;
+                       const char *user;
+                       const char *permission;
+               };
+               const char *keys[KeyIdx_Count];
+       };
 };
 
 struct data_value {