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. In principle, a binder afb-daemon is launched by application
 113 instance. But for services, a binder</p>
 114
 115 <a name="Exchanging.tokens"></a>
 116 <h3>Exchanging tokens</h3>
 117
 118 <p>At start, the framework communicate a common secret to both the binder
 119 and its client: the application. This initial secret is the
 120 initial token.</p>
 121
 122 <p>For each of its client application, the binder manages a current active
 123 token. The initial token is the default active token. It is the expected
 124 token for new clients.</p>
 125 </body>
 126 </html>