aboutsummaryrefslogtreecommitdiffstats
path: root/doc/afb-application-writing.html
blob: f1e89904d515eb947897ab970494e3065840994c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
<html>
<head>
  <link rel="stylesheet" type="text/css" href="doc.css">
  <meta charset="UTF-8">
</head>
<body>
<a name="HOWTO.WRITE.an.APPLICATION.above.AGL.FRAMEWORK"></a>
<h1>HOWTO WRITE an APPLICATION above AGL FRAMEWORK</h1>

<pre><code>version: 1
Date:    30 mai 2016
Author:  José Bollo
</code></pre>

<p><ul>
 <li><a href="#HOWTO.WRITE.an.APPLICATION.above.AGL.FRAMEWORK">HOWTO WRITE an APPLICATION above AGL FRAMEWORK</a>
 <ul>
  <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="#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>
<h3>Writing an HTML5 application</h3>

<p>Developpers of HTML5 applications (client side) can easyly create
applications for AGL framework using their prefered
HTML framework.</p>

<p>Developpers can also create powerful server side plugins to improve
their application. This server side plugin should return the mime-type
application/json and can be accessed either by HTTP or by Websockets.</p>

<p>In a near future, the JSON-RPC protocol will be available together
with the current x-afb-json1 protocol.</p>

<p>Two examples of HTML5 applications are given:</p>

<ul>
<li><p><a href="https://github.com/iotbzh/afb-client">afb-client</a> a simple &ldquo;hello world&rdquo; application</p></li>
<li><p><a href="https://github.com/iotbzh/afm-client">afm-client</a> a simple &ldquo;Home screen&rdquo; application</p></li>
</ul>


<a name="Writing.a.Qt.application"></a>
<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>

<p>It is even possible to write a QML application.
It is demontrated by the sample application token-websock:</p>

<ul>
<li><a href="https://github.com/iotbzh/afb-daemon/blob/master/test/token-websock.qml">token-websock</a>
a simple &ldquo;hello world&rdquo; application in QML</li>
</ul>


<a name="Writing.a.C.application"></a>
<h3>Writing a C application</h3>

<p>C applications can use the binder afb-daemon through a websocket connection.</p>

<p>The library <strong>libafbwsc</strong> is made for C clients that want
to connect to the afb-daemon binder.</p>

<p>The program <strong>afb-client-demo</strong> is the C program that use
the provided library <strong>libafbwsc</strong>.
Its source code is here
<a href="https://github.com/iotbzh/afb-daemon/blob/master/src/afb-client-demo.c">src/afb-client-demo.c</a>.</p>

<p>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.</p>

<a name="Handling.sessions.within.applications"></a>
<h2>Handling sessions within applications</h2>

<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
socket isn&rsquo;t currently implemented but could be used in near future).
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 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>