-HOWTO WRITE an APPLICATION above AGL FRAMEWORK
-==============================================
- version: 1
- Date: 30 mai 2016
- Author: José Bollo
+How to write an application on top of AGL FRAMEWORK
+====================================================
-TABLE-OF-CONTENT-HERE
-
-Programmation Languages for Applications
+Programming Languages for Applications
-----------------------------------------
### Writing an HTML5 application
applications for AGL framework using their preferred
HTML5 framework.
-Developers may also take advantage of powerful server side plugins to improve
-application behavior. Server side plugins return an application/json mine-type
+Developers may also take advantage of powerful server side bindings to improve
+application behavior. Server side bindings return an application/json mine-type
and can be accessed though either HTTP or Websockets.
-In a near future, JSON-RPC protocol should be added to complete current x-afb-json1 protocol.
+In a near future, JSON-RPC protocol should be added to complete the current
+x-afb-json1 protocol.
Two examples of HTML5 applications are given:
-- [afb-client](https://github.com/iotbzh/afb-client) a simple "hello world" application template
+- [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
-- [afm-client](https://github.com/iotbzh/afm-client) a simple "Home screen" application template
+- [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
### Writing a Qt application
-Writing Qt applications is also supported. Qt offers standard API to send request through HTTP or WebSockets.
+Writing Qt applications is also supported. Qt offers standard API to send
+request through HTTP or WebSockets.
-It is also possible to write QML applications. A sample QML application [token-websock] is avaliable..
+It is also possible to write QML applications. A sample QML application
+[token-websock] is available:
-- [token-websock](https://github.com/iotbzh/afb-daemon/blob/master/test/token-websock.qml)
+- [token-websock](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=blob;f=test/token-websock.qml)
a simple "hello world" application in QML
-### Writing "C" application
+### Writing a "C" application
C applications can use afb-daemon binder through a websocket connection.
The program **afb-client-demo** is the C example that use
**libafbwsc** library.
Source code is available here
-[src/afb-client-demo.c](https://github.com/iotbzh/afb-daemon/blob/master/src/afb-client-demo.c).
+[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).
Current implementation relies on libsystemd and file descriptors.
This model might be review in the future to support secure sockets
-and free the dependency with libsystemd.
+and get rid of libsystemd dependency.
Handling sessions within applications
-------------------------------------
-Applications should understand sessions and tokens management when interacting with afb-daemon binder.
+Applications should understand sessions and token management when interacting
+with afb-daemon binder.
-Applications are communicating with their private binder(afb-daemon) using
-a network connection or potentially any other connection channel. While current version
-does not yet implement unix domain this feature might be added in a near future.
-Developers need to be warn that HTTP protocol is a none connected protocol. This prevents
-from using HTTP socket connection to authenticate clients.
+Applications communicate with their private binder(afb-daemon) using
+a network connection or potentially any other connection channel. While the
+current version does not yet implement Unix socket, this feature might be added
+in the near future. Developers need to be warn that HTTP protocol is a none
+connected protocol and that using HTTP socket connection to authenticate
+clients is not supported.
For this reason, the binder should authenticate the application
by using a shared secret. The secret is named "token" and the identification
### Handling sessions
-Plugins and other binder feature need to keep track of client
-instances. This is especially important for plugins running as services
+Bindings and other binder features need to keep track of client
+instances. This is especially important for bindings running as services
as they may typically have to keep each client's data separated.
For HTML5 applications, the web runtime handles the cookie of session
that the binder afb-daemon automatically sets.
-Session identifier can be set using the parameter
-**uuid** or **x-afb-uuid** in URI requests. Within current version of the
-framework session UUID is supported by both HTTP requests and websocket negotiation.
+Session identifier can be set using the parameter **uuid** or **x-afb-uuid** in
+URI requests. Within current version of the framework session UUID is supported
+by both HTTP requests and websocket negotiation.
### Exchanging tokens
At application start, AGL framework communicates a shared secret to both binder
-and client application. This initial secret is called the "initial token".
+and client application. This initial secret is called the "**initial token**".
For each of its client application, the binder manages a current active
token for session management. This authentication token can be use to restrict
-access to some plugin's methods.
+the access to some binding's methods.
The token must be included in URI request on HTTP or during websockets
connection using parameter **token** or **x-afb-token**.
### Example of session management
-In following examples, we suppose that **afb-daemon** is launched with something equivalent to:
+In following examples, we suppose that **afb-daemon** is launched with something
+equivalent to:
$ afb-daemon --port=1234 --token=123456 [...]
-making the expectation that **AuthLogin** plugin is requested as default.
+making the expectation that **AuthLogin** binding is requested as default.
#### Using curl
#### Using afb-client-demo
+> The program is packaged within AGL in the rpm **libafbwsc-dev**
+
Here is an example of exchange using **afb-client-demo**:
$ afb-client-demo ws://localhost:1234/api?token=123456
Replies use javascript object returned as serialized JSON.
-This object contains at least 2 mandatory fields of name **jtype** and **request**
-and one optional field of name **response**.
+This object contains at least 2 mandatory fields of name **jtype** and
+**request** and one optional field of name **response**.
+
+### Template
+
+This is a template of replies:
+
+```json
+{
+ "jtype": "afb-reply",
+ "request": {
+ "status": "success",
+ "info": "informationnal text",
+ "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
+ "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
+ "reqid": "application-generated-id-23456"
+ },
+ "response": ....any response object....
+}
+```
### Field jtype
**reqid** is of type string. It is sent in response to HTTP requests
that added a parameter of name **reqid** or **x-afb-reqid** at request time.
-Value returns in the reply has the exact same value as the one received in the request.
+Value returns in the reply has the exact same value as the one received in the
+request.
### Field response
-This field response optionally contains an object returned when request succeeded.
+This field response optionally contains an object returned when request
+succeeded.
+
+Format of events
+----------------
+
+Events are javascript object serialized as JSON.
+
+This object contains at least 2 mandatory fields of name **jtype** and **event**
+and one optional field of name **data**.
### Template
-This is a template of replies:
+Here is a template of event:
- {
- "jtype": "afb-reply",
- "request": {
- "status": "success",
- "info": "informationnal text",
- "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
- "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
- "reqid": "application-generated-id-23456"
- },
- "response": ....any response object....
- }
+```json
+{
+ "jtype": "afb-event",
+ "event": "sample_api_name/sample_event_name",
+ "data": ...any event data...
+}
+```
+
+### Field jtype
+
+The field **jtype** must have a value of type string equal to **"afb-event"**.
+
+### Field event
+
+The field **event** carries the event's name.
+
+The name of the event is made of two parts separated by a slash:
+the name of the name of the API that generated the event
+and the name of event within the API.
+
+### Field data
+
+This field data if present holds the data carried by the event.
Code Review / src / app-framework-binder.git / blobdiff