From f5c013e32d1c8ee931bec45cee7bc04c5d536d50 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jos=C3=A9=20Bollo?= Date: Sun, 29 May 2016 22:15:41 +0200 Subject: [PATCH] Adds documentation MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Also remove a old cmakefile Change-Id: I2748514934790043a15bb48d1d06bd82967d4494 Signed-off-by: JosÃ© Bollo --- doc/afb-application-writing.html | 40 ++++++++++++++++++++++ doc/afb-application-writing.md | 27 +++++++++++++++ doc/afb-overview.html | 72 ++++++++++++++++++++++++++++++++++++++++ doc/afb-overview.md | 58 ++++++++++++++++++++++++++++++++ doc/afb-plugin-writing.html | 18 +++++----- plugins/samples/CMakeLists.txt2 | 47 -------------------------- src/afb-client-demo.c | 53 +++++++++++++++++++++-------- 7 files changed, 246 insertions(+), 69 deletions(-) create mode 100644 doc/afb-application-writing.html create mode 100644 doc/afb-application-writing.md create mode 100644 doc/afb-overview.html create mode 100644 doc/afb-overview.md delete mode 100644 plugins/samples/CMakeLists.txt2 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 @@ + + + + + + + +

HOWTO WRITE an APPLICATION above AGL FRAMEWORK

+ +

version: 1
+Date:    29 mai 2016
+Author:  JosÃ© Bollo
+

+ +

HOWTO WRITE an APPLICATION above AGL FRAMEWORK +
- Writing a C application
+

+ + +

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.

+ +

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-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 @@ + + + + + + + +

Overview of AFB-DAEMON

+ +

version: 1
+Date:    29 mai 2016
+Author:  JosÃ© Bollo
+

+ +

Overview of AFB-DAEMON +
- Roles of afb-daemon
+

+ + +

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:

+ +

It acts as a gateway for the application to access the system;
It acts as an HTTP server for serving files to HTML5 applications;
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-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 - + @@ -1070,7 +1070,7 @@ formatting messages if the message must not be output.

- + @@ -1078,13 +1078,13 @@ formatting messages if the message must not be output.

- + - + @@ -1096,13 +1096,13 @@ formatting messages if the message must not be output.

- + - + @@ -1426,13 +1426,13 @@ endif()

Constant name	Constant name	Meaning
Macro	Verbosity	Meaning	Meaning	syslog level
ERROR	0	Error conditions	Error conditions	3
WARNING	1	Warning conditions	Warning conditions	4
INFO	2	Informational	Informational	6
DEBUG	3	Debug-level messages	Debug-level messages	7

- + - + @@ -1452,7 +1452,7 @@ endif() - + 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; -- 2.16.6

Variable	Variable	Meaning
afb_FOUND	afb_FOUND	Set to 1 if afb-daemon plugin development files exist
The ‘-I’ preprocessor flags (w/o the ‘-I’) for compiling afb-daemon plugins
afb_CFLAGS	afb_CFLAGS	All required cflags for compiling afb-daemon plugins