diff options
| -rw-r--r-- | doc/afb-application-writing.html | 46 | ||||
| -rw-r--r-- | doc/afb-application-writing.md | 34 | ||||
| -rw-r--r-- | doc/afb-daemon.html | 171 | ||||
| -rw-r--r-- | doc/afb-daemon.md | 158 | ||||
| -rw-r--r-- | doc/afb-overview.html | 153 | ||||
| -rw-r--r-- | doc/afb-overview.md | 159 |
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 “hello world” 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 “one-shot” 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 “one-shot” 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. + + |