docs/4_APIs_and_Services/4.3_Application_Framework_Binder/5_Binder_Application_writing_guide/Binder_Application_writing_guide.md

   1 ---
   2 edit_link: ''
   3 title: Binder Application writing guide
   4 origin_url: >-
   5   https://git.automotivelinux.org/src/app-framework-binder/plain/docs/afb-application-writing.md?h=master
   6 ---
   7
   8 <!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/apis_services/master/app-framework-binder-developer-guides-api-services-book.yml -->
   9
  10 # How to write an application on top of AGL FRAMEWORK
  11
  12 ## Programming Languages for Applications
  13
  14 ### Writing an HTML5 application
  15
  16 Developers of HTML5 applications (client side) can easily create
  17 applications for AGL framework using their preferred
  18 HTML5 framework.
  19
  20 Developers may also take advantage of powerful server side bindings to improve
  21 application behavior.
  22 Server side bindings return an application/json mine-type
  23 and can be accessed though either HTTP or Websockets.
  24
  25 In a near future, JSON-RPC protocol should be added to complete the current
  26 x-afb-json1 protocol.
  27
  28 Two examples of HTML5 applications are given:
  29
  30 - [afb-client](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-demo.git;a=tree;f=afb-client) a simple "hello world" application template
  31
  32 - [afm-client](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-demo.git;a=tree;f=afm-client) a simple "Home screen" application template
  33
  34 ### Writing a Qt application
  35
  36 Writing Qt applications is also supported.
  37 Qt offers standard API to send request through HTTP or WebSockets.
  38
  39 It is also possible to write QML applications.
  40 A sample QML application [token-websock] is available:
  41
  42 - [token-websock](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=blob;f=test/token-websock.qml)
  43
  44 A simple "hello world" application in QML
  45
  46 ### Writing a "C" application
  47
  48 C applications can use afb-daemon binder through a websocket connection.
  49
  50 The library **libafbwsc** is provided for C clients that need
  51 to connect with an afb-daemon binder.
  52
  53 The program **afb-client-demo** is the C example that uses the
  54 **libafbwsc** library.
  55 Source code is available here
  56 [src/afb-client-demo.c](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=blob;f=src/afb-client-demo.c).
  57
  58 Current implementation relies on libsystemd and file descriptors.
  59 This model may be reviewed in the future to support secure sockets
  60 and get rid of libsystemd dependency.
  61
  62 ### Handling sessions within applications
  63
  64 Applications should understand sessions and token management when interacting
  65 with afb-daemon binder.
  66
  67 Applications communicate with their private binder (afb-daemon) using
  68 a network connection or any other potential connection channel.
  69 While the current version does not yet implement Unix socket,
  70 this feature might be added in the near future.
  71 Developers need to be warn that HTTP protocol is a none
  72 connected protocol and that using HTTP socket connection to authenticate
  73 clients is not supported.
  74
  75 For this reason, the binder should authenticate the application
  76 by using a shared secret.
  77 The secret is named "token" and the identification of client is named "session.”
  78
  79 The examples **token-websock.qml** and **afb-client** are demonstrating
  80 how authentication and sessions are managed.
  81
  82 ### Handling sessions
  83
  84 Bindings and other binder features need to keep track of client
  85 instances.
  86 This is especially important for bindings running as services
  87 as they may typically have to keep each client's data separated.
  88
  89 For HTML5 applications, the web runtime handles the cookie of the session
  90 that the binder afb-daemon automatically sets.
  91
  92 Session identifier can be set using the parameter **uuid** or **x-afb-uuid** in
  93 URI requests.
  94 Within current version of the framework session UUID is supported
  95 by both HTTP requests and websocket negotiation.
  96
  97 ### Exchanging tokens
  98
  99 At application start, AGL framework communicates a shared secret to both binder
 100 and client application.
 101 This initial secret is called the "**initial token**".
 102
 103 For each of its client application, the binder manages a current active
 104 token for session management.
 105 This authentication token can be use to restrict the access to some binding's methods.
 106
 107 The token must be included in URI request on HTTP or during websockets
 108 connection using parameter **token** or **x-afb-token**.
 109
 110 To ensure security, tokens must be refreshed periodically.
 111
 112 ### Example of session management
 113
 114 In following examples, we suppose that **afb-daemon** is launched with something
 115 equivalent to:
 116
 117 ```bash
 118 afb-daemon --port=1234 --token=123456 [...]
 119 ```
 120
 121 making the expectation that **AuthLogin** binding is requested as default.
 122
 123 #### Using curl
 124
 125 First, connects with the initial token, 123456:
 126
 127 ```bash
 128 $ curl http://localhost:1234/api/auth/connect?token=123456
 129 {
 130   "jtype": "afb-reply",
 131   "request": {
 132      "status": "success",
 133      "token": "0aef6841-2ddd-436d-b961-ae78da3b5c5f",
 134      "uuid": "850c4594-1be1-4e9b-9fcc-38cc3e6ff015"
 135   },
 136   "response": {"token": "A New Token and Session Context Was Created"}
 137 }
 138 ```
 139
 140 It returns an answer containing session UUID, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015,
 141 and a refreshed token, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015.
 142
 143 Check if session and token is valid:
 144
 145 ```bash
 146 $ curl http://localhost:1234/api/auth/check?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 147 {
 148   "jtype": "afb-reply",
 149   "request": {"status":"success"},
 150   "response": {"isvalid":true}
 151 }
 152 ```
 153
 154 Refresh the token:
 155
 156 ```bash
 157 $ curl http://localhost:1234/api/auth/refresh?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 158 {
 159   "jtype": "afb-reply",
 160   "request": {
 161      "status":"success",
 162      "token":"b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9"
 163   },
 164   "response": {"token":"Token was refreshed"}
 165 }
 166 ```
 167
 168 Close the session:
 169
 170 ```bash
 171 $ curl http://localhost:1234/api/auth/logout?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 172 {
 173   "jtype": "afb-reply",
 174   "request": {"status": "success"},
 175   "response": {"info":"Token and all resources are released"}
 176 }
 177 ```
 178
 179 Checking on closed session for uuid should be refused:
 180
 181 ```bash
 182 $ curl http://localhost:1234/api/auth/check?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 183 {
 184   "jtype": "afb-reply",
 185   "request": {
 186     "status": "failed",
 187     "info": "invalid token's identity"
 188   }
 189 }
 190 ```
 191
 192 #### Using afb-client-demo
 193
 194 - The program is packaged within AGL in the rpm **libafbwsc-dev**
 195
 196 Here is an example of exchange using **afb-client-demo**:
 197
 198 ```bash
 199 $ afb-client-demo ws://localhost:1234/api?token=123456
 200 auth connect
 201 ON-REPLY 1:auth/connect: {"jtype":"afb-reply","request":{"status":"success",
 202    "token":"63f71a29-8b52-4f9b-829f-b3028ba46b68","uuid":"5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1"},
 203    "response":{"token":"A New Token and Session Context Was Created"}}
 204 auth check
 205 ON-REPLY 2:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
 206 auth refresh
 207 ON-REPLY 4:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
 208    "token":"8b8ba8f4-1b0c-48fa-962d-4a00a8c9157e"},"response":{"token":"Token was refreshed"}}
 209 auth check
 210 ON-REPLY 5:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
 211 auth refresh
 212 ON-REPLY 6:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
 213    "token":"e83b36f8-d945-463d-b983-5d8ed73ba529"},"response":{"token":"Token was refreshed"}}
 214 ```
 215
 216 After closing connection, reconnect as here after:
 217
 218 ```bash
 219 $ afb-client-demo ws://localhost:1234/api?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1 auth check
 220 ON-REPLY 1:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
 221 ```
 222
 223 Same connection check using **curl**:
 224
 225 ```bash
 226 $ curl http://localhost:1234/api/auth/check?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1
 227 {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
 228 ```
 229
 230 ### Format of replies
 231
 232 Replies use javascript object returned as serialized JSON.
 233
 234 This object contains at least 2 mandatory fields of name **jtype** and
 235 **request** and one optional field of name **response**.
 236
 237 #### Template of replies
 238
 239 This is a template of replies:
 240
 241 ```json
 242 {
 243    "jtype": "afb-reply",
 244    "request": {
 245       "status": "success",
 246       "info": "informationnal text",
 247       "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
 248       "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
 249       "reqid": "application-generated-id-23456"
 250    },
 251    "response": ....any response object....
 252 }
 253 ```
 254
 255 #### Field jtype of replies
 256
 257 The field **jtype** must have a value of type string equal to **"afb-reply"**.
 258
 259 #### Field request of replies
 260
 261 The field **request** must have a value of type object.
 262 This request object has at least one field named **status**
 263 and four optional fields named **info**, **token**, **uuid**, **reqid**.
 264
 265 ##### Subfield request.status
 266
 267 **status** must have a value of type string. This string is equal to **"success"**
 268 only in case of success.
 269
 270 ##### Subfield request.info
 271
 272 **info** is of type string and represent optional information added to the reply.
 273
 274 ##### Subfield request.token
 275
 276 **token** is of type string. It is sent either at session creation
 277 or when the token is refreshed.
 278
 279 ##### Subfield request.uuid
 280
 281 **uuid** is of type string. It is sent at session creation.
 282
 283 ##### Subfield request.reqid
 284
 285 **reqid** is of type string. It is sent in response to HTTP requests
 286 that added a parameter of name **reqid** or **x-afb-reqid** at request time.
 287 Value returns in the reply has the exact same value as the one received in the
 288 request.
 289
 290 #### Field response of replies
 291
 292 This field response optionally contains an object returned when request
 293 succeeded.
 294
 295 ### Format of events
 296
 297 Events are javascript object serialized as JSON.
 298
 299 This object contains at least 2 mandatory fields of name **jtype** and **event**
 300 and one optional field of name **data**.
 301
 302 #### Template of event
 303
 304 Here is a template of event:
 305
 306 ```json
 307 {
 308    "jtype": "afb-event",
 309    "event": "sample_api_name/sample_event_name",
 310    "data": ...any event data...
 311 }
 312 ```
 313
 314 #### Field jtype of event
 315
 316 The field **jtype** must have a value of type string equal to **"afb-event"**.
 317
 318 #### Field event of event
 319
 320 The field **event** carries the event's name.
 321
 322 The name of the event is made of two parts separated by a slash:
 323 the name of the name of the API that generated the event
 324 and the name of event within the API.
 325
 326 #### Field data of event
 327
 328 This field data if present holds the data carried by the event.