Adds documentation

Also remove a old cmakefile Change-Id: I2748514934790043a15bb48d1d06bd82967d4494 Signed-off-by: José Bollo <jose.bollo@iot.bzh>
author: José Bollo <jose.bollo@iot.bzh> 2016-05-29 22:15:41 +0200
committer: José Bollo <jose.bollo@iot.bzh> 2016-05-29 23:53:55 +0200
commit: f5c013e32d1c8ee931bec45cee7bc04c5d536d50 (patch)
tree: e2f33d0e9e6a7873154cfe4a20b6d9b0c413caaf
parent: a4487d8a46d3e4400bf73ce817fa1a34cde31a6f (diff)
7 files changed, 246 insertions, 69 deletions
diff --git a/doc/afb-application-writing.html b/doc/afb-application-writing.html
new file mode 100644
index 00000000..adb5ca7b
--- /dev/null
+++ b/doc/afb-application-writing.html
@@ -0,0 +1,40 @@
+<html>
+<head>
+  <link rel="stylesheet" type="text/css" href="doc.css">
+  <meta charset="UTF-8">
+</head>
+<body>
+<a name="HOWTO.WRITE.an.APPLICATION.above.AGL.FRAMEWORK"></a>
+<h1>HOWTO WRITE an APPLICATION above AGL FRAMEWORK</h1>
+
+<pre><code>version: 1
+Date:    29 mai 2016
+Author:  José Bollo
+</code></pre>
+
+<p><ul>
+ <li><a href="#HOWTO.WRITE.an.APPLICATION.above.AGL.FRAMEWORK">HOWTO WRITE an APPLICATION above AGL FRAMEWORK</a>
+ <ul>
+  <li><a href="#Writing.a.C.application">Writing a C application</a></li>
+ </ul>
+ </li>
+</ul></p>
+
+<a name="Writing.a.C.application"></a>
+<h2>Writing a C application</h2>
+
+<p>C applications can use the binder afb-daemon through a websocket connection.</p>
+
+<p>The library <strong>libafbwsc</strong> is made for C clients that want
+to connect to the afb-daemon binder.</p>
+
+<p>The program <strong>afb-client-demo</strong> is the C program that use
+the provided library <strong>libafbwsc</strong>.
+Its source code is here
+<a href="https://github.com/iotbzh/afb-daemon/blob/master/src/afb-client-demo.c">src/afb-client-demo.c</a>.</p>
+
+<p>The current implementation use libsystemd and file descriptors.
+This may be changed in the future to also support secure sockets
+and being less dependant of libsystemd.</p>
+</body>
+</html>
diff --git a/doc/afb-application-writing.md b/doc/afb-application-writing.md
new file mode 100644
index 00000000..a7099a86
--- /dev/null
+++ b/doc/afb-application-writing.md
@@ -0,0 +1,27 @@
+HOWTO WRITE an APPLICATION above AGL FRAMEWORK
+==============================================
+    version: 1
+    Date:    29 mai 2016
+    Author:  José Bollo
+
+TABLE-OF-CONTENT-HERE
+
+
+Writing a C application
+-----------------------
+
+C applications can use the binder afb-daemon through a websocket connection.
+
+The library **libafbwsc** is made for C clients that want
+to connect to the afb-daemon binder.
+
+The program **afb-client-demo** is the C program that use
+the provided library **libafbwsc**.
+Its source code is here
+[src/afb-client-demo.c](https://github.com/iotbzh/afb-daemon/blob/master/src/afb-client-demo.c).
+
+The current implementation use libsystemd and file descriptors.
+This may be changed in the future to also support secure sockets
+and being less dependant of libsystemd.
+
+
diff --git a/doc/afb-overview.html b/doc/afb-overview.html
new file mode 100644
index 00000000..15331282
--- /dev/null
+++ b/doc/afb-overview.html
@@ -0,0 +1,72 @@
+<html>
+<head>
+  <link rel="stylesheet" type="text/css" href="doc.css">
+  <meta charset="UTF-8">
+</head>
+<body>
+<a name="Overview.of.AFB-DAEMON"></a>
+<h1>Overview of AFB-DAEMON</h1>
+
+<pre><code>version: 1
+Date:    29 mai 2016
+Author:  José Bollo
+</code></pre>
+
+<p><ul>
+ <li><a href="#Overview.of.AFB-DAEMON">Overview of AFB-DAEMON</a>
+ <ul>
+  <li><a href="#Roles.of.afb-daemon">Roles of afb-daemon</a></li>
+ </ul>
+ </li>
+</ul></p>
+
+<a name="Roles.of.afb-daemon"></a>
+<h2>Roles of afb-daemon</h2>
+
+<p>The name <strong>afb-daemon</strong> stands for <em>Application
+Framework Binder Daemon</em>. That is why afb-daemon
+is also named <strong><em>the binder</em></strong>.</p>
+
+<p><strong>Afb-daemon</strong> is in charge to bind one instance of
+an application to the AGL framework and AGL system.</p>
+
+<p>On the following figure, you can use a typical use
+of afb-daemon:</p>
+
+<pre><code>. . . . . . . . . . . . . . . . . . . . . . . . . .
+.        Isolated security context                .
+.                                                 .
+.        +------------------------------+         .
+.        |                              |         .
+.        |    A P P L I C A T I O N     |         .
+.        |                              |         .
+.        +--------------+---------------+         .
+.                       |                         .
+.                       |                         .
+.   +-------------------+----------------------+  .
+.   |                            :             |  .
+.   |    A F B - D A E M O N     :   PLUGINS   |  .
+.   |                            :             |  .
+.   +-------------------+----------------------+  .
+.                       |                         .
+. . . . . . . . . . . . | . . . . . . . . . . . . .
+                        |
+                        v
+                   AGL SYSTEM
+</code></pre>
+
+<p>The application and its companion binder run in secured and isolated
+environment set for them. Applications are intended to access to AGL
+system through the binder.</p>
+
+<p>The binder afb-daemon serves multiple purposes:</p>
+
+<ol>
+<li><p>It acts as a gateway for the application to access the system;</p></li>
+<li><p>It acts as an HTTP server for serving files to HTML5 applications;</p></li>
+<li><p>It allows HTML5 applications to have native extensions subject
+to security enforcement for accessing hardware ressources or
+for speeding parts of algorithm.</p></li>
+</ol>
+</body>
+</html>
diff --git a/doc/afb-overview.md b/doc/afb-overview.md
new file mode 100644
index 00000000..a5b19231
--- /dev/null
+++ b/doc/afb-overview.md
@@ -0,0 +1,58 @@
+Overview of AFB-DAEMON
+======================
+    version: 1
+    Date:    29 mai 2016
+    Author:  José Bollo
+
+TABLE-OF-CONTENT-HERE
+
+Roles of afb-daemon
+-------------------
+
+The name **afb-daemon** stands for *Application
+Framework Binder Daemon*. That is why afb-daemon
+is also named ***the binder***.
+
+**Afb-daemon** is in charge to bind one instance of
+an application to the AGL framework and AGL system.
+
+On the following figure, you can use a typical use
+of afb-daemon:
+
+	. . . . . . . . . . . . . . . . . . . . . . . . . .
+	.        Isolated security context                .
+	.                                                 .
+	.        +------------------------------+         .
+	.        |                              |         .
+	.        |    A P P L I C A T I O N     |         .
+	.        |                              |         .
+	.        +--------------+---------------+         .
+	.                       |                         .
+	.                       |                         .
+	.   +-------------------+----------------------+  .
+	.   |                            :             |  .
+	.   |    A F B - D A E M O N     :   PLUGINS   |  .
+	.   |                            :             |  .
+	.   +-------------------+----------------------+  .
+	.                       |                         .
+	. . . . . . . . . . . . | . . . . . . . . . . . . .
+	                        |
+	                        v
+	                   AGL SYSTEM
+
+The application and its companion binder run in secured and isolated
+environment set for them. Applications are intended to access to AGL
+system through the binder.
+
+The binder afb-daemon serves multiple purposes:
+
+1. It acts as a gateway for the application to access the system;
+
+2. It acts as an HTTP server for serving files to HTML5 applications;
+
+3. It allows HTML5 applications to have native extensions subject
+to security enforcement for accessing hardware ressources or
+for speeding parts of algorithm.
+
+
+
diff --git a/doc/afb-plugin-writing.html b/doc/afb-plugin-writing.html
index b80006f4..1864cfdf 100644
--- a/doc/afb-plugin-writing.html
+++ b/doc/afb-plugin-writing.html
@@ -967,7 +967,7 @@ enumeration but the wrapper of constant definitions that can be mixed using bitw
 <table>
 <thead>
 <tr>
-<th>Constant name        </th>
+<th>Constant name            </th>
 <th> Meaning</th>
 </tr>
 </thead>
@@ -1070,7 +1070,7 @@ formatting messages if the message must not be output.</p>
 <tr>
 <th>Macro   </th>
 <th style="text-align:center;"> Verbosity </th>
-<th> Meaning                       </th>
+<th> Meaning                           </th>
 <th style="text-align:center;"> syslog level</th>
 </tr>
 </thead>
@@ -1078,13 +1078,13 @@ formatting messages if the message must not be output.</p>
 <tr>
 <td>ERROR   </td>
 <td style="text-align:center;">     0     </td>
-<td> Error conditions              </td>
+<td> Error conditions                  </td>
 <td style="text-align:center;">     3</td>
 </tr>
 <tr>
 <td>WARNING </td>
 <td style="text-align:center;">     1     </td>
-<td> Warning conditions            </td>
+<td> Warning conditions                </td>
 <td style="text-align:center;">     4</td>
 </tr>
 <tr>
@@ -1096,13 +1096,13 @@ formatting messages if the message must not be output.</p>
 <tr>
 <td>INFO    </td>
 <td style="text-align:center;">     2     </td>
-<td> Informational                 </td>
+<td> Informational                     </td>
 <td style="text-align:center;">     6</td>
 </tr>
 <tr>
 <td>DEBUG   </td>
 <td style="text-align:center;">     3     </td>
-<td> Debug-level messages          </td>
+<td> Debug-level messages              </td>
 <td style="text-align:center;">     7</td>
 </tr>
 </tbody>
@@ -1426,13 +1426,13 @@ endif()
 <table>
 <thead>
 <tr>
-<th>Variable      </th>
+<th>Variable          </th>
 <th> Meaning</th>
 </tr>
 </thead>
 <tbody>
 <tr>
-<td>afb_FOUND     </td>
+<td>afb_FOUND         </td>
 <td> Set to 1 if afb-daemon plugin development files exist</td>
 </tr>
 <tr>
@@ -1452,7 +1452,7 @@ endif()
 <td> The &lsquo;-I&rsquo; preprocessor flags (w/o the &lsquo;-I&rsquo;) for compiling afb-daemon plugins</td>
 </tr>
 <tr>
-<td>afb_CFLAGS    </td>
+<td>afb_CFLAGS        </td>
 <td> All required cflags for compiling afb-daemon plugins</td>
 </tr>
 </tbody>
diff --git a/plugins/samples/CMakeLists.txt2 b/plugins/samples/CMakeLists.txt2
deleted file mode 100644
index 357f16a6..00000000
--- a/plugins/samples/CMakeLists.txt2
+++ /dev/null
@@ -1,47 +0,0 @@
-
-INCLUDE_DIRECTORIES(${include_dirs})
-
-ADD_LIBRARY(helloWorld-api MODULE HelloWorld.c)
-SET_TARGET_PROPERTIES(helloWorld-api PROPERTIES
-	PREFIX ""
-	LINK_FLAGS "-Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/export.map"
-)
-TARGET_LINK_LIBRARIES(helloWorld-api ${link_libraries})
-INSTALL(TARGETS helloWorld-api
-        LIBRARY DESTINATION ${plugin_install_dir})
-
-ADD_LIBRARY(samplePost-api MODULE SamplePost.c)
-SET_TARGET_PROPERTIES(samplePost-api PROPERTIES
-	PREFIX ""
-	LINK_FLAGS "-Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/export.map"
-)
-TARGET_LINK_LIBRARIES(samplePost-api ${link_libraries})
-INSTALL(TARGETS samplePost-api
-        LIBRARY DESTINATION ${plugin_install_dir})
-
-ADD_LIBRARY(clientCtx-api MODULE ClientCtx.c)
-SET_TARGET_PROPERTIES(clientCtx-api PROPERTIES
-	PREFIX ""
-	LINK_FLAGS "-Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/export.map"
-)
-TARGET_LINK_LIBRARIES(clientCtx-api ${link_libraries})
-INSTALL(TARGETS clientCtx-api
-        LIBRARY DESTINATION ${plugin_install_dir})
-
-ADD_LIBRARY(ClientLogin-api MODULE ClientLogin.c)
-SET_TARGET_PROPERTIES(ClientLogin-api PROPERTIES
-	PREFIX ""
-	LINK_FLAGS "-Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/export.map"
-)
-TARGET_LINK_LIBRARIES(ClientLogin-api ${link_libraries})
-INSTALL(TARGETS ClientLogin-api
-        LIBRARY DESTINATION ${plugin_install_dir})
-
-ADD_LIBRARY(tic-tac-toe MODULE tic-tac-toe.c)
-SET_TARGET_PROPERTIES(tic-tac-toe PROPERTIES
-	PREFIX ""
-	LINK_FLAGS "-Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/export.map"
-)
-TARGET_LINK_LIBRARIES(tic-tac-toe ${link_libraries})
-INSTALL(TARGETS tic-tac-toe
-        LIBRARY DESTINATION ${plugin_install_dir})
diff --git a/src/afb-client-demo.c b/src/afb-client-demo.c
index 6344d6a3..6f494a6a 100644
--- a/src/afb-client-demo.c
+++ b/src/afb-client-demo.c
@@ -34,62 +34,78 @@
 #include "afb-wsj1.h"
 #include "afb-ws-client.h"
 
+/* declaration of functions */
 static void on_hangup(void *closure, struct afb_wsj1 *wsj1);
 static void on_call(void *closure, const char *api, const char *verb, struct afb_wsj1_msg *msg);
 static void on_event(void *closure, const char *event, struct afb_wsj1_msg *msg);
 static int io_event_callback(sd_event_source *src, int fd, uint32_t revents, void *closure);
 static void emit(const char *api, const char *verb, const char *object);
 
+/* the callback interface for wsj1 */
 static struct afb_wsj1_itf itf = {
 	.on_hangup = on_hangup,
 	.on_call = on_call,
 	.on_event = on_event
 };
 
+/* global variables */
 static struct afb_wsj1 *wsj1;
 static int exonrep;
 static int callcount;
 static sd_event_source *evsrc;
 
+/* print usage of the program */
 static void usage(int status, char *arg0)
 {
 	char *name = strrchr(arg0, '/');
 	name = name ? name + 1 : arg0;
-	fprintf(status ? stderr : stdin, "usage: %s uri [api verb data]\n", name);
+	fprintf(status ? stderr : stdout, "usage: %s uri [api verb [data]]\n", name);
 	exit(status);
 }
 
+/* entry function */
 int main(int ac, char **av, char **env)
 {
-	if (ac != 2 && ac != 5)
+	/* check the argument count */
+	if (ac != 2 && ac != 4 && ac != 5)
 		usage(1, av[0]);
+
+	/* emit error and exit if requested */
 	if (!strcmp(av[1], "-h") || !strcmp(av[1], "--help"))
 		usage(0, av[0]);
 
+	/* connect the websocket wsj1 to the uri given by the first argument */
 	wsj1 = afb_ws_client_connect_wsj1(av[1], &itf, NULL);
 	if (wsj1 == NULL) {
 		fprintf(stderr, "connection to %s failed: %m\n", av[1]);
 		return 1;
 	}
 
+	/* test the behaviour */
 	if (ac == 2) {
+		/* get requests from stdin */
 		fcntl(0, F_SETFL, O_NONBLOCK);
 		sd_event_add_io(afb_common_get_event_loop(), &evsrc, 0, EPOLLIN, io_event_callback, NULL);
 	} else {
+		/* the request is defined by the arguments */
 		exonrep = 1;
 		emit(av[2], av[3], av[4]);
 	}
+
+	/* loop until end */
 	for(;;)
 		sd_event_run(afb_common_get_event_loop(), 30000000);
 	return 0;
 }
 
+/* called when wsj1 hangsup */
 static void on_hangup(void *closure, struct afb_wsj1 *wsj1)
 {
 	printf("ON-HANGUP\n");
 	exit(0);
 }
 
+/* called when wsj1 receives a method invocation */
 static void on_call(void *closure, const char *api, const char *verb, struct afb_wsj1_msg *msg)
 {
 	int rc;
@@ -99,20 +115,13 @@ static void on_call(void *closure, const char *api, const char *verb, struct afb
 		fprintf(stderr, "replying failed: %m\n");
 }
 
+/* called when wsj1 receives an event */
 static void on_event(void *closure, const char *event, struct afb_wsj1_msg *msg)
 {
 	printf("ON-EVENT %s(%s)\n", event, afb_wsj1_msg_object_s(msg));
 }
 
-static void event(const char *event, const char *object)
-{
-	int rc;
-
-	rc = afb_wsj1_send_event_s(wsj1, event, object);
-	if (rc < 0)
-		fprintf(stderr, "sending !%s(%s) failed: %m\n", event, object);
-}
-
+/* called when wsj1 receives a reply */
 static void on_reply(void *closure, struct afb_wsj1_msg *msg)
 {
 	printf("ON-REPLY %s: %s\n", (char*)closure, afb_wsj1_msg_object_s(msg));
@@ -123,13 +132,17 @@ static void on_reply(void *closure, struct afb_wsj1_msg *msg)
 		exit(0);
 }
 
+/* makes a call */
 static void call(const char *api, const char *verb, const char *object)
 {
 	static int num = 0;
 	char *key;
 	int rc;
 
+	/* allocates an id for the request */
 	rc = asprintf(&key, "%d:%s/%s", ++num, api, verb);
+
+	/* send the request */
 	callcount++;
 	rc = afb_wsj1_call_s(wsj1, api, verb, object, on_reply, key);
 	if (rc < 0) {
@@ -138,14 +151,28 @@ static void call(const char *api, const char *verb, const char *object)
 	}
 }
 
+/* sends an event */
+static void event(const char *event, const char *object)
+{
+	int rc;
+
+	rc = afb_wsj1_send_event_s(wsj1, event, object);
+	if (rc < 0)
+		fprintf(stderr, "sending !%s(%s) failed: %m\n", event, object);
+}
+
+/* emits either a call (when api!='!') or an event */
 static void emit(const char *api, const char *verb, const char *object)
 {
+	if (object == NULL || object[0] == 0)
+		object = "null";
 	if (api[0] == '!' && api[1] == 0)
 		event(verb, object);
 	else
 		call(api, verb, object);
 }
 
+/* called when something happens on stdin */
 static int io_event_callback(sd_event_source *src, int fd, uint32_t revents, void *closure)
 {
 	static size_t count = 0;
@@ -171,7 +198,7 @@ static int io_event_callback(sd_event_source *src, int fd, uint32_t revents, voi
 	count += (size_t)rc;
 
 	/* normalise the buffer content */
-	/* TODO: handle backspace \x7f */
+	/* TODO: handle backspace \x7f ? */
 
 	/* process the lines */
 	pos = 0;
@@ -186,7 +213,7 @@ static int io_event_callback(sd_event_source *src, int fd, uint32_t revents, voi
 		rest[0] = i; while(i < count && line[i] != '\n') i++; rest[1] = i;
 		if (i == count) break;
 		line[i++] = 0;
-		if (api[0] == api[1] || verb[0] == verb[1] || rest[0] == rest[1])
+		if (api[0] == api[1] || verb[0] == verb[1])
 			fprintf(stderr, "bad line: %s\n", line+pos);
 		else {
 			line[api[1]] = line[verb[1]] = 0;
author	José Bollo <jose.bollo@iot.bzh>	2016-05-29 22:15:41 +0200
committer	José Bollo <jose.bollo@iot.bzh>	2016-05-29 23:53:55 +0200
commit	f5c013e32d1c8ee931bec45cee7bc04c5d536d50 (patch)
tree	e2f33d0e9e6a7873154cfe4a20b6d9b0c413caaf
parent	a4487d8a46d3e4400bf73ce817fa1a34cde31a6f (diff)