Updated Dpid.txt to the new DPIP API. Added more comments in hello.c

1 files changed, 27 insertions, 7 deletions

diff --git a/dpi/hello.c b/dpi/hello.c
index 6fc3b8c6..4643efc5 100644
--- a/dpi/hello.c
+++ b/dpi/hello.c
@@ -45,14 +45,22 @@ int main(void)
    char *choice[] = {"Window was closed", "Yes", "No",
                       "Could be", "It's OK", "Cancel"};
                    /* "Could>be", ">It's OK", "Can'>cel"};  --for testing */
-   int choice_num;
+   int choice_num = -1;
 
    MSG("starting...\n");
+   /* sleep(20) */
 
-   /* Initialize the SockHandler */
+   /* Initialize the SockHandler.
+    * This means we'll use stdin for input and stdout for output.
+    * In case of a server dpi, we'd use a socket and pass its file descriptor
+    * twice (e.g. a_Dpip_dsh_new(sock_fd, sock_fd, 1024).
+    * (Note: by now the last parameter is not used) */
    sh = a_Dpip_dsh_new(STDIN_FILENO, STDOUT_FILENO, 2*1024);
 
-   /* Authenticate our client... */
+   /* Authenticate our client...
+    * As we're using Internet domain sockets, DPIP checks whether the client
+    * runs with the user's ID, by means of a shared secret. The DPIP API does
+    * the work for us. */
    if (!(dpip_tag = a_Dpip_dsh_read_token(sh, 1)) ||
        a_Dpip_check_auth(dpip_tag) < 0) {
       MSG("can't authenticate request: %s\n", dStrerror(errno));
@@ -61,14 +69,22 @@ int main(void)
    }
    dFree(dpip_tag);
 
-   /* Read the dpi command from STDIN */
+   /* Read the dpi command from STDIN
+    * Now we're past the authentication phase, let's see what's dillo
+    * asking from us. a_Dpip_dsh_read_token() will block and return
+    * a full dpip token or null on error (it's commented in dpip.c) */
    dpip_tag = a_Dpip_dsh_read_token(sh, 1);
    MSG("tag = [%s]\n", dpip_tag);
 
+   /* Now that we have the dpip_tag, let's isolate the command and url */
    cmd = a_Dpip_get_attr(dpip_tag, "cmd");
    url = a_Dpip_get_attr(dpip_tag, "url");
 
 /*-- Dialog part */
+/* This is the dialog window. This is an example of interaction with
+ * the user. If you're starting to understand dpis, comment this out
+ * by switching to "#if 0" and the dialog will be disabled. */
+#if 1
 {
    char *dpip_tag2, *dialog_msg;
 
@@ -94,9 +110,11 @@ int main(void)
    dFree(dialog_msg);
    dFree(dpip_tag2);
 }
+#endif
 /*-- EOD part */
 
-   /* Start sending our answer */
+   /* Start sending our answer.
+    * (You can read the comments for DPIP API functions in dpip/dpip.c) */
    d_cmd = a_Dpip_build_cmd("cmd=%s url=%s", "start_send_page", url);
    a_Dpip_dsh_write_str(sh, 0, d_cmd);
    dFree(d_cmd);
@@ -115,7 +133,7 @@ int main(void)
       "<big><em>Dialog question:</em> Do you want to see the hello page?<br>\n"
       "<em>Answer received:</em> <b>%s</b></big> </table>\n"
       "<hr>\n",
-      choice[choice_num]);
+      choice_num < 0 ? "There was NO dialog!" : choice[choice_num]);
 
    /* Show the dpip tag we received */
    esc_tag = Escape_html_str(dpip_tag);
@@ -128,7 +146,9 @@ int main(void)
 
 
    /* Now something more interesting,
-    * fork a command and show its feedback */
+    * fork a command and show its feedback.
+    * (An example of generating dynamic content with an external
+    *  program). */
    if (cmd && url) {
       child_cmd = dStrdup("date -R");
       MSG("[%s]\n", child_cmd);