aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/afb-application-writing.html46
-rw-r--r--doc/afb-application-writing.md34
-rw-r--r--doc/afb-daemon.html171
-rw-r--r--doc/afb-daemon.md158
-rw-r--r--doc/afb-overview.html153
-rw-r--r--doc/afb-overview.md159
6 files changed, 369 insertions, 352 deletions
diff --git a/doc/afb-application-writing.html b/doc/afb-application-writing.html
index 7c0278da..f1e89904 100644
--- a/doc/afb-application-writing.html
+++ b/doc/afb-application-writing.html
@@ -15,21 +15,28 @@ Author: José Bollo
<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.an.HTML5.application">Writing an HTML5 application</a></li>
- <li><a href="#Writing.a.Qt.application">Writing a Qt application</a></li>
- <li><a href="#Writing.a.C.application">Writing a C application</a></li>
+ <li><a href="#Languages.for.writing.Applications">Languages for writing Applications</a>
+ <ul>
+ <li><a href="#Writing.an.HTML5.application">Writing an HTML5 application</a></li>
+ <li><a href="#Writing.a.Qt.application">Writing a Qt application</a></li>
+ <li><a href="#Writing.a.C.application">Writing a C application</a></li>
+ </ul>
+ </li>
<li><a href="#Handling.sessions.within.applications">Handling sessions within applications</a>
<ul>
- <li><a href="#Exchanging.tokens">Exchanging tokens</a></li>
<li><a href="#Handling.sessions">Handling sessions</a></li>
+ <li><a href="#Exchanging.tokens">Exchanging tokens</a></li>
</ul>
</li>
</ul>
</li>
</ul></p>
+<a name="Languages.for.writing.Applications"></a>
+<h2>Languages for writing Applications</h2>
+
<a name="Writing.an.HTML5.application"></a>
-<h2>Writing an HTML5 application</h2>
+<h3>Writing an HTML5 application</h3>
<p>Developpers of HTML5 applications (client side) can easyly create
applications for AGL framework using their prefered
@@ -51,7 +58,7 @@ with the current x-afb-json1 protocol.</p>
<a name="Writing.a.Qt.application"></a>
-<h2>Writing a Qt application</h2>
+<h3>Writing a Qt application</h3>
<p>Writing Qt applications is also possible because Qt offers APIs to
make HTTP queries and to connect using WebSockets.</p>
@@ -66,7 +73,7 @@ a simple &ldquo;hello world&rdquo; application in QML</li>
<a name="Writing.a.C.application"></a>
-<h2>Writing a C application</h2>
+<h3>Writing a C application</h3>
<p>C applications can use the binder afb-daemon through a websocket connection.</p>
@@ -85,8 +92,8 @@ and being less dependant of libsystemd.</p>
<a name="Handling.sessions.within.applications"></a>
<h2>Handling sessions within applications</h2>
-<a name="Exchanging.tokens"></a>
-<h3>Exchanging tokens</h3>
+<p>Applications must be aware of the the features session and token
+when they interact with the binder afb-daemon.</p>
<p>Applications are communicating with their binder afb-daemon using
a network connection or a kind of network connection (unix domain
@@ -95,12 +102,25 @@ Also, HTTP protocol is not a connected protocol. It means that
the socket connection can not be used to authenticate a client.</p>
<p>For this reason, the binder should authenticate the application
-by using a commonly shared secret named token.</p>
-
-<p>At start, the framework communicate a common secret to both the binder
-and its client: the application. When the application</p>
+by using a commonly shared secret named token and the identification
+of the client named session.</p>
<a name="Handling.sessions"></a>
<h3>Handling sessions</h3>
+
+<p>Plugins and features of the binder need to keep track of the client
+instances. In principle, a binder afb-daemon is launched by application
+instance. But for services, a binder</p>
+
+<a name="Exchanging.tokens"></a>
+<h3>Exchanging tokens</h3>
+
+<p>At start, the framework communicate a common secret to both the binder
+and its client: the application. This initial secret is the
+initial token.</p>
+
+<p>For each of its client application, the binder manages a current active
+token. The initial token is the default active token. It is the expected
+token for new clients.</p>
</body>
</html>
diff --git a/doc/afb-application-writing.md b/doc/afb-application-writing.md
index 7d2cd635..ead31a91 100644
--- a/doc/afb-application-writing.md
+++ b/doc/afb-application-writing.md
@@ -6,8 +6,10 @@ HOWTO WRITE an APPLICATION above AGL FRAMEWORK
TABLE-OF-CONTENT-HERE
-Writing an HTML5 application
-----------------------------
+Languages for writing Applications
+----------------------------------
+
+### Writing an HTML5 application
Developpers of HTML5 applications (client side) can easyly create
applications for AGL framework using their prefered
@@ -26,8 +28,7 @@ Two examples of HTML5 applications are given:
- [afm-client](https://github.com/iotbzh/afm-client) a simple "Home screen" application
-Writing a Qt application
-------------------------
+### Writing a Qt application
Writing Qt applications is also possible because Qt offers APIs to
make HTTP queries and to connect using WebSockets.
@@ -38,8 +39,7 @@ It is demontrated by the sample application token-websock:
- [token-websock](https://github.com/iotbzh/afb-daemon/blob/master/test/token-websock.qml)
a simple "hello world" application in QML
-Writing a C application
------------------------
+### Writing a C application
C applications can use the binder afb-daemon through a websocket connection.
@@ -58,7 +58,8 @@ and being less dependant of libsystemd.
Handling sessions within applications
-------------------------------------
-### Exchanging tokens
+Applications must be aware of the the features session and token
+when they interact with the binder afb-daemon.
Applications are communicating with their binder afb-daemon using
a network connection or a kind of network connection (unix domain
@@ -67,11 +68,24 @@ Also, HTTP protocol is not a connected protocol. It means that
the socket connection can not be used to authenticate a client.
For this reason, the binder should authenticate the application
-by using a commonly shared secret named token.
+by using a commonly shared secret named token and the identification
+of the client named session.
+
+### Handling sessions
+
+Plugins and features of the binder need to keep track of the client
+instances. In principle, a binder afb-daemon is launched by application
+instance. But for services, a binder
+
+### Exchanging tokens
At start, the framework communicate a common secret to both the binder
-and its client: the application. When the application
+and its client: the application. This initial secret is the
+initial token.
+
+For each of its client application, the binder manages a current active
+token. The initial token is the default active token. It is the expected
+token for new clients.
-### Handling sessions
diff --git a/doc/afb-daemon.html b/doc/afb-daemon.html
deleted file mode 100644
index 85b24980..00000000
--- a/doc/afb-daemon.html
+++ /dev/null
@@ -1,171 +0,0 @@
-<html>
-<head>
- <link rel="stylesheet" type="text/css" href="doc.css">
- <meta charset="UTF-8">
-</head>
-<body>
-<a name="The.binder.AFB-DAEMON"></a>
-<h1>The binder AFB-DAEMON</h1>
-
-<pre><code>version: 1
-Date: 30 mai 2016
-Author: José Bollo
-</code></pre>
-
-<p><ul>
- <li><a href="#The.binder.AFB-DAEMON">The binder AFB-DAEMON</a>
- <ul>
- <li><a href="#Launching.the.binder.afb-daemon">Launching the binder afb-daemon</a></li>
- <li><a href="#Working.with.afb-daemon">Working with afb-daemon</a></li>
- <li><a href="#Future.of.afb-daemon">Future of afb-daemon</a></li>
- </ul>
- </li>
-</ul></p>
-
-<a name="Launching.the.binder.afb-daemon"></a>
-<h2>Launching the binder afb-daemon</h2>
-
-<p>The launch options for binder <strong>afb-daemon</strong> are:</p>
-
-<pre><code> --help
-
- Prints help with available options
-
- --version
-
- Display version and copyright
-
- --verbose
-
- Increases the verbosity, can be repeated
-
- --port=xxxx
-
- HTTP listening TCP port [default 1234]
-
- --rootdir=xxxx
-
- HTTP Root Directory [default $AFBDIR or else $HOME/.AFB]
-
- --rootbase=xxxx
-
- Angular Base Root URL [default /opa]
-
- This is used for any application of kind OPA (one page application).
- When set, any missing document whose url has the form /opa/zzz
- is translated to /opa/#!zzz
-
- --rootapi=xxxx
-
- HTML Root API URL [default /api]
-
- The plugins are available within that url.
-
- --alias=xxxx
-
- Maps a path located anywhere in the file system to the
- a subdirectory. The syntax for mapping a PATH to the
- subdirectory NAME is: --alias=/NAME:PATH.
-
- Example: --alias=/icons:/usr/share/icons maps the
- content of /usr/share/icons within the subpath /icons.
-
- This option can be repeated.
-
- --apitimeout=xxxx
-
- Plugin API timeout in seconds [default 20]
-
- Defines how many seconds maximum a method is allowed to run.
- 0 means no limit.
-
- --cntxtimeout=xxxx
-
- Client Session Timeout in seconds [default 3600]
-
- --cache-eol=xxxx
-
- Client cache end of live [default 100000 that is 27,7 hours]
-
- --sessiondir=xxxx
-
- Sessions file path [default rootdir/sessions]
-
- --ldpaths=xxxx
-
- Load Plugins from given paths separated by colons
- as for dir1:dir2:plugin1.so:... [default = $libdir/afb]
-
- You can mix path to directories and to plugins.
- The sub-directories of the given directories are searched
- recursively.
-
- The plugins are the files terminated by '.so' (the extension
- so denotes shared object) that contain the public entry symbol.
-
- --plugin=xxxx
-
- Load the plugin of given path.
-
- --token=xxxx
-
- Initial Secret token to authenticate.
-
- If not set, no client can authenticate.
-
- If set to the empty string, then any initial token is accepted.
-
- --mode=xxxx
-
- Set the mode: either local, remote or global.
-
- The mode indicate if the application is run locally on the host
- or remotely through network.
-
- --readyfd=xxxx
-
- Set the #fd to signal when ready
-
- If set, the binder afb-daemon will write "READY=1\n" on the file
- descriptor whose number if given (/proc/self/fd/xxx).
-
- --dbus-client=xxxx
-
- Transparent binding to a binder afb-daemon service through dbus.
-
- It creates an API of name xxxx that is implemented remotely
- and queried via DBUS.
-
- --dbus-server=xxxx
-
- Provides a binder afb-daemon service through dbus.
-
- The name xxxx must be the name of an API defined by a plugin.
- This API is exported through DBUS.
-
- --foreground
-
- Get all in foreground mode (default)
-
- --daemon
-
- Get all in background mode
-</code></pre>
-
-<a name="Working.with.afb-daemon"></a>
-<h2>Working with afb-daemon</h2>
-
-<a name="Future.of.afb-daemon"></a>
-<h2>Future of afb-daemon</h2>
-
-<ul>
-<li><p>Integration of the protocol JSON-RPC for the websockets.</p></li>
-<li><p>The binder afb-daemon would launch the applications directly.</p></li>
-<li><p>The current setting of mode (local/remote/global) might be reworked to a
-mechanism for querying configuration variables.</p></li>
-<li><p>Implements &ldquo;one-shot&rdquo; initial token. It means that after its first
-authenticated use, the initial token is removed and no client can connect
-anymore.</p></li>
-</ul>
-</body>
-</html>
diff --git a/doc/afb-daemon.md b/doc/afb-daemon.md
deleted file mode 100644
index 72d5eacb..00000000
--- a/doc/afb-daemon.md
+++ /dev/null
@@ -1,158 +0,0 @@
-The binder AFB-DAEMON
-=====================
- version: 1
- Date: 30 mai 2016
- Author: José Bollo
-
-TABLE-OF-CONTENT-HERE
-
-Launching the binder afb-daemon
--------------------------------
-
-The launch options for binder **afb-daemon** are:
-
- --help
-
- Prints help with available options
-
- --version
-
- Display version and copyright
-
- --verbose
-
- Increases the verbosity, can be repeated
-
- --port=xxxx
-
- HTTP listening TCP port [default 1234]
-
- --rootdir=xxxx
-
- HTTP Root Directory [default $AFBDIR or else $HOME/.AFB]
-
- --rootbase=xxxx
-
- Angular Base Root URL [default /opa]
-
- This is used for any application of kind OPA (one page application).
- When set, any missing document whose url has the form /opa/zzz
- is translated to /opa/#!zzz
-
- --rootapi=xxxx
-
- HTML Root API URL [default /api]
-
- The plugins are available within that url.
-
- --alias=xxxx
-
- Maps a path located anywhere in the file system to the
- a subdirectory. The syntax for mapping a PATH to the
- subdirectory NAME is: --alias=/NAME:PATH.
-
- Example: --alias=/icons:/usr/share/icons maps the
- content of /usr/share/icons within the subpath /icons.
-
- This option can be repeated.
-
- --apitimeout=xxxx
-
- Plugin API timeout in seconds [default 20]
-
- Defines how many seconds maximum a method is allowed to run.
- 0 means no limit.
-
- --cntxtimeout=xxxx
-
- Client Session Timeout in seconds [default 3600]
-
- --cache-eol=xxxx
-
- Client cache end of live [default 100000 that is 27,7 hours]
-
- --sessiondir=xxxx
-
- Sessions file path [default rootdir/sessions]
-
- --ldpaths=xxxx
-
- Load Plugins from given paths separated by colons
- as for dir1:dir2:plugin1.so:... [default = $libdir/afb]
-
- You can mix path to directories and to plugins.
- The sub-directories of the given directories are searched
- recursively.
-
- The plugins are the files terminated by '.so' (the extension
- so denotes shared object) that contain the public entry symbol.
-
- --plugin=xxxx
-
- Load the plugin of given path.
-
- --token=xxxx
-
- Initial Secret token to authenticate.
-
- If not set, no client can authenticate.
-
- If set to the empty string, then any initial token is accepted.
-
- --mode=xxxx
-
- Set the mode: either local, remote or global.
-
- The mode indicate if the application is run locally on the host
- or remotely through network.
-
- --readyfd=xxxx
-
- Set the #fd to signal when ready
-
- If set, the binder afb-daemon will write "READY=1\n" on the file
- descriptor whose number if given (/proc/self/fd/xxx).
-
- --dbus-client=xxxx
-
- Transparent binding to a binder afb-daemon service through dbus.
-
- It creates an API of name xxxx that is implemented remotely
- and queried via DBUS.
-
- --dbus-server=xxxx
-
- Provides a binder afb-daemon service through dbus.
-
- The name xxxx must be the name of an API defined by a plugin.
- This API is exported through DBUS.
-
- --foreground
-
- Get all in foreground mode (default)
-
- --daemon
-
- Get all in background mode
-
-
-Working with afb-daemon
------------------------
-
-
-
-Future of afb-daemon
---------------------
-
-- Integration of the protocol JSON-RPC for the websockets.
-
-- The binder afb-daemon would launch the applications directly.
-
-- The current setting of mode (local/remote/global) might be reworked to a
-mechanism for querying configuration variables.
-
-- Implements "one-shot" initial token. It means that after its first
-authenticated use, the initial token is removed and no client can connect
-anymore.
-
-
diff --git a/doc/afb-overview.html b/doc/afb-overview.html
index cfb5de75..8e03ff10 100644
--- a/doc/afb-overview.html
+++ b/doc/afb-overview.html
@@ -24,6 +24,8 @@ Author: José Bollo
</ul>
</li>
<li><a href="#The.plugins.of.the.binder.afb-daemon">The plugins of the binder afb-daemon</a></li>
+ <li><a href="#Launching.the.binder.afb-daemon">Launching the binder afb-daemon</a></li>
+ <li><a href="#Future.development.of.afb-daemon">Future development of afb-daemon</a></li>
</ul>
</li>
</ul></p>
@@ -213,5 +215,156 @@ written with any language through web technologies ala JSON RPC.</p>
<p>A specific document shows</p>
+
+<a name="Launching.the.binder.afb-daemon"></a>
+<h2>Launching the binder afb-daemon</h2>
+
+<p>The launch options for binder <strong>afb-daemon</strong> are:</p>
+
+<pre><code> --help
+
+ Prints help with available options
+
+ --version
+
+ Display version and copyright
+
+ --verbose
+
+ Increases the verbosity, can be repeated
+
+ --port=xxxx
+
+ HTTP listening TCP port [default 1234]
+
+ --rootdir=xxxx
+
+ HTTP Root Directory [default $AFBDIR or else $HOME/.AFB]
+
+ --rootbase=xxxx
+
+ Angular Base Root URL [default /opa]
+
+ This is used for any application of kind OPA (one page application).
+ When set, any missing document whose url has the form /opa/zzz
+ is translated to /opa/#!zzz
+
+ --rootapi=xxxx
+
+ HTML Root API URL [default /api]
+
+ The plugins are available within that url.
+
+ --alias=xxxx
+
+ Maps a path located anywhere in the file system to the
+ a subdirectory. The syntax for mapping a PATH to the
+ subdirectory NAME is: --alias=/NAME:PATH.
+
+ Example: --alias=/icons:/usr/share/icons maps the
+ content of /usr/share/icons within the subpath /icons.
+
+ This option can be repeated.
+
+ --apitimeout=xxxx
+
+ Plugin API timeout in seconds [default 20]
+
+ Defines how many seconds maximum a method is allowed to run.
+ 0 means no limit.
+
+ --cntxtimeout=xxxx
+
+ Client Session Timeout in seconds [default 3600]
+
+ --cache-eol=xxxx
+
+ Client cache end of live [default 100000 that is 27,7 hours]
+
+ --sessiondir=xxxx
+
+ Sessions file path [default rootdir/sessions]
+
+ --session-max=xxxx
+
+ Maximum count of simultaneous sessions [default 10]
+
+ --ldpaths=xxxx
+
+ Load Plugins from given paths separated by colons
+ as for dir1:dir2:plugin1.so:... [default = $libdir/afb]
+
+ You can mix path to directories and to plugins.
+ The sub-directories of the given directories are searched
+ recursively.
+
+ The plugins are the files terminated by '.so' (the extension
+ so denotes shared object) that contain the public entry symbol.
+
+ --plugin=xxxx
+
+ Load the plugin of given path.
+
+ --token=xxxx
+
+ Initial Secret token to authenticate.
+
+ If not set, no client can authenticate.
+
+ If set to the empty string, then any initial token is accepted.
+
+ --mode=xxxx
+
+ Set the mode: either local, remote or global.
+
+ The mode indicate if the application is run locally on the host
+ or remotely through network.
+
+ --readyfd=xxxx
+
+ Set the #fd to signal when ready
+
+ If set, the binder afb-daemon will write "READY=1\n" on the file
+ descriptor whose number if given (/proc/self/fd/xxx).
+
+ --dbus-client=xxxx
+
+ Transparent binding to a binder afb-daemon service through dbus.
+
+ It creates an API of name xxxx that is implemented remotely
+ and queried via DBUS.
+
+ --dbus-server=xxxx
+
+ Provides a binder afb-daemon service through dbus.
+
+ The name xxxx must be the name of an API defined by a plugin.
+ This API is exported through DBUS.
+
+ --foreground
+
+ Get all in foreground mode (default)
+
+ --daemon
+
+ Get all in background mode
+</code></pre>
+
+<a name="Future.development.of.afb-daemon"></a>
+<h2>Future development of afb-daemon</h2>
+
+<ul>
+<li><p>The binder afb-daemon would launch the applications directly.</p></li>
+<li><p>The current setting of mode (local/remote/global) might be reworked to a
+mechanism for querying configuration variables.</p></li>
+<li><p>Implements &ldquo;one-shot&rdquo; initial token. It means that after its first
+authenticated use, the initial token is removed and no client can connect
+anymore.</p></li>
+<li><p>Creates some intrinsic APIs.</p></li>
+<li><p>Make the service connection using WebSocket not DBUS.</p></li>
+<li><p>Management of targetted events.</p></li>
+<li><p>Securisation of LOA.</p></li>
+<li><p>Integration of the protocol JSON-RPC for the websockets.</p></li>
+</ul>
</body>
</html>
diff --git a/doc/afb-overview.md b/doc/afb-overview.md
index a5dcdf0b..37fdd0c3 100644
--- a/doc/afb-overview.md
+++ b/doc/afb-overview.md
@@ -182,3 +182,162 @@ This simple idea is declined to serves multiple purposes:
3. provide customers services
A specific document shows
+
+
+Launching the binder afb-daemon
+-------------------------------
+
+The launch options for binder **afb-daemon** are:
+
+ --help
+
+ Prints help with available options
+
+ --version
+
+ Display version and copyright
+
+ --verbose
+
+ Increases the verbosity, can be repeated
+
+ --port=xxxx
+
+ HTTP listening TCP port [default 1234]
+
+ --rootdir=xxxx
+
+ HTTP Root Directory [default $AFBDIR or else $HOME/.AFB]
+
+ --rootbase=xxxx
+
+ Angular Base Root URL [default /opa]
+
+ This is used for any application of kind OPA (one page application).
+ When set, any missing document whose url has the form /opa/zzz
+ is translated to /opa/#!zzz
+
+ --rootapi=xxxx
+
+ HTML Root API URL [default /api]
+
+ The plugins are available within that url.
+
+ --alias=xxxx
+
+ Maps a path located anywhere in the file system to the
+ a subdirectory. The syntax for mapping a PATH to the
+ subdirectory NAME is: --alias=/NAME:PATH.
+
+ Example: --alias=/icons:/usr/share/icons maps the
+ content of /usr/share/icons within the subpath /icons.
+
+ This option can be repeated.
+
+ --apitimeout=xxxx
+
+ Plugin API timeout in seconds [default 20]
+
+ Defines how many seconds maximum a method is allowed to run.
+ 0 means no limit.
+
+ --cntxtimeout=xxxx
+
+ Client Session Timeout in seconds [default 3600]
+
+ --cache-eol=xxxx
+
+ Client cache end of live [default 100000 that is 27,7 hours]
+
+ --sessiondir=xxxx
+
+ Sessions file path [default rootdir/sessions]
+
+ --session-max=xxxx
+
+ Maximum count of simultaneous sessions [default 10]
+
+ --ldpaths=xxxx
+
+ Load Plugins from given paths separated by colons
+ as for dir1:dir2:plugin1.so:... [default = $libdir/afb]
+
+ You can mix path to directories and to plugins.
+ The sub-directories of the given directories are searched
+ recursively.
+
+ The plugins are the files terminated by '.so' (the extension
+ so denotes shared object) that contain the public entry symbol.
+
+ --plugin=xxxx
+
+ Load the plugin of given path.
+
+ --token=xxxx
+
+ Initial Secret token to authenticate.
+
+ If not set, no client can authenticate.
+
+ If set to the empty string, then any initial token is accepted.
+
+ --mode=xxxx
+
+ Set the mode: either local, remote or global.
+
+ The mode indicate if the application is run locally on the host
+ or remotely through network.
+
+ --readyfd=xxxx
+
+ Set the #fd to signal when ready
+
+ If set, the binder afb-daemon will write "READY=1\n" on the file
+ descriptor whose number if given (/proc/self/fd/xxx).
+
+ --dbus-client=xxxx
+
+ Transparent binding to a binder afb-daemon service through dbus.
+
+ It creates an API of name xxxx that is implemented remotely
+ and queried via DBUS.
+
+ --dbus-server=xxxx
+
+ Provides a binder afb-daemon service through dbus.
+
+ The name xxxx must be the name of an API defined by a plugin.
+ This API is exported through DBUS.
+
+ --foreground
+
+ Get all in foreground mode (default)
+
+ --daemon
+
+ Get all in background mode
+
+
+Future development of afb-daemon
+--------------------------------
+
+- The binder afb-daemon would launch the applications directly.
+
+- The current setting of mode (local/remote/global) might be reworked to a
+mechanism for querying configuration variables.
+
+- Implements "one-shot" initial token. It means that after its first
+authenticated use, the initial token is removed and no client can connect
+anymore.
+
+- Creates some intrinsic APIs.
+
+- Make the service connection using WebSocket not DBUS.
+
+- Management of targetted events.
+
+- Securisation of LOA.
+
+- Integration of the protocol JSON-RPC for the websockets.
+
+