doc/afb-application-writing.md

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