doc/afb-application-writing.html

   1 <html>
   2 <head>
   3   <link rel="stylesheet" type="text/css" href="doc.css">
   4   <meta charset="UTF-8">
   5 </head>
   6 <body>
   7 <a name="HOWTO.WRITE.an.APPLICATION.above.AGL.FRAMEWORK"></a>
   8 <h1>HOWTO WRITE an APPLICATION above AGL FRAMEWORK</h1>
   9
  10 <pre><code>version: 1
  11 Date:    30 mai 2016
  12 Author:  José Bollo
  13 </code></pre>
  14
  15 <p><ul>
  16  <li><a href="#HOWTO.WRITE.an.APPLICATION.above.AGL.FRAMEWORK">HOWTO WRITE an APPLICATION above AGL FRAMEWORK</a>
  17  <ul>
  18   <li><a href="#Languages.for.writing.Applications">Languages for writing Applications</a>
  19   <ul>
  20    <li><a href="#Writing.an.HTML5.application">Writing an HTML5 application</a></li>
  21    <li><a href="#Writing.a.Qt.application">Writing a Qt application</a></li>
  22    <li><a href="#Writing.a.C.application">Writing a C application</a></li>
  23   </ul>
  24   </li>
  25   <li><a href="#Handling.sessions.within.applications">Handling sessions within applications</a>
  26   <ul>
  27    <li><a href="#Handling.sessions">Handling sessions</a></li>
  28    <li><a href="#Exchanging.tokens">Exchanging tokens</a></li>
  29   </ul>
  30   </li>
  31  </ul>
  32  </li>
  33 </ul></p>
  34
  35 <a name="Languages.for.writing.Applications"></a>
  36 <h2>Languages for writing Applications</h2>
  37
  38 <a name="Writing.an.HTML5.application"></a>
  39 <h3>Writing an HTML5 application</h3>
  40
  41 <p>Developpers of HTML5 applications (client side) can easyly create
  42 applications for AGL framework using their prefered
  43 HTML framework.</p>
  44
  45 <p>Developpers can also create powerful server side plugins to improve
  46 their application. This server side plugin should return the mime-type
  47 application/json and can be accessed either by HTTP or by Websockets.</p>
  48
  49 <p>In a near future, the JSON-RPC protocol will be available together
  50 with the current x-afb-json1 protocol.</p>
  51
  52 <p>Two examples of HTML5 applications are given:</p>
  53
  54 <ul>
  55 <li><p><a href="https://github.com/iotbzh/afb-client">afb-client</a> a simple &ldquo;hello world&rdquo; application</p></li>
  56 <li><p><a href="https://github.com/iotbzh/afm-client">afm-client</a> a simple &ldquo;Home screen&rdquo; application</p></li>
  57 </ul>
  58
  59
  60 <a name="Writing.a.Qt.application"></a>
  61 <h3>Writing a Qt application</h3>
  62
  63 <p>Writing Qt applications is also possible because Qt offers APIs to
  64 make HTTP queries and to connect using WebSockets.</p>
  65
  66 <p>It is even possible to write a QML application.
  67 It is demontrated by the sample application token-websock:</p>
  68
  69 <ul>
  70 <li><a href="https://github.com/iotbzh/afb-daemon/blob/master/test/token-websock.qml">token-websock</a>
  71 a simple &ldquo;hello world&rdquo; application in QML</li>
  72 </ul>
  73
  74
  75 <a name="Writing.a.C.application"></a>
  76 <h3>Writing a C application</h3>
  77
  78 <p>C applications can use the binder afb-daemon through a websocket connection.</p>
  79
  80 <p>The library <strong>libafbwsc</strong> is made for C clients that want
  81 to connect to the afb-daemon binder.</p>
  82
  83 <p>The program <strong>afb-client-demo</strong> is the C program that use
  84 the provided library <strong>libafbwsc</strong>.
  85 Its source code is here
  86 <a href="https://github.com/iotbzh/afb-daemon/blob/master/src/afb-client-demo.c">src/afb-client-demo.c</a>.</p>
  87
  88 <p>The current implementation use libsystemd and file descriptors.
  89 This may be changed in the future to also support secure sockets
  90 and being less dependant of libsystemd.</p>
  91
  92 <a name="Handling.sessions.within.applications"></a>
  93 <h2>Handling sessions within applications</h2>
  94
  95 <p>Applications must be aware of the the features session and token
  96 when they interact with the binder afb-daemon.</p>
  97
  98 <p>Applications are communicating with their binder afb-daemon using
  99 a network connection or a kind of network connection (unix domain
 100 socket isn&rsquo;t currently implemented but could be used in near future).
 101 Also, HTTP protocol is not a connected protocol. It means that
 102 the socket connection can not be used to authenticate a client.</p>
 103
 104 <p>For this reason, the binder should authenticate the application
 105 by using a commonly shared secret named token and the identification
 106 of the client named session.</p>
 107
 108 <a name="Handling.sessions"></a>
 109 <h3>Handling sessions</h3>
 110
 111 <p>Plugins and features of the binder need to keep track of the client
 112 instances. This of importance for plugins running as service
 113 because they may have to separate the data of each client.</p>
 114
 115 <p>For common HTML5 browser running an HTML5 application.</p>
 116
 117 <a name="Exchanging.tokens"></a>
 118 <h3>Exchanging tokens</h3>
 119
 120 <p>At start, the framework communicates a common secret to both the binder
 121 and its client: the application. This initial secret is the
 122 initial token.</p>
 123
 124 <p>For each of its client application, the binder manages a current active
 125 token. The initial token is the default active token. It is the expected
 126 token for new clients.</p>
 127 </body>
 128 </html>