Some english improvement of the documentation.
Change-Id: I066c41d657a1921ed7dcc46dafcc7c65d122239c
Signed-off-by: José Bollo <jose.bollo@iot.bzh>
The library **libafbwsc** is provided for C clients that need
to connect with an afb-daemon binder.
-The program **afb-client-demo** is the C example that use
+The program **afb-client-demo** is the C example that uses the
**libafbwsc** library.
Source code is available here
[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
+This model may be reviewed in the future to support secure sockets
and get rid of libsystemd dependency.
### Handling sessions within applications
with afb-daemon binder.
Applications communicate with their private binder (afb-daemon) using
-a network connection or potentially any other connection channel.
+a network connection or any other potential 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
For this reason, the binder should authenticate the application
by using a shared secret.
-The secret is named "token" and the identification of client is named "session".
+The secret is named "token" and the identification of client is named "session.”
The examples **token-websock.qml** and **afb-client** are demonstrating
how authentication and sessions are managed.
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
+For HTML5 applications, the web runtime handles the cookie of the session
that the binder afb-daemon automatically sets.
Session identifier can be set using the parameter **uuid** or **x-afb-uuid** in
# Overview of the bindings
-The ***binder*** serves files through HTTP protocol and offers to
-developers the capability to offer application API methods through HTTP or
+The ***binder*** serves files through HTTP protocol and offers developers the capability to offer application API methods through HTTP or
WebSocket protocol.
The ***bindings*** are used to add **API** to ***binders***.
This part describes how to write a ***binding*** for ***binder***
or in other words how to add a new **API** to the system.
-Excepting this summary, this section target developers.
+This section target developers.
This section shortly explain how to write a binding
using the C programming language.
It is convenient to install the ***binder*** on the
desktop used for writing the binding.
-It allows easy debug and test.
+It allows for easy debug and test.
## Nature of a binding
It contains several **verbs** that implement the ***binding***
functionalities.
Each of these **verbs** is a **method** that
-processes requests of applications and sends result.
+processes requests of applications and sends results.
The ***binding***'s methods are invoked by HTTP or websocket
requests.
- The include to get for creating a binding
- How to declare the API offered by the binding
-- How to handle request made to the binding
+- How to handle requests made to the binding
### Getting declarations for the binding
# Debugging binder and bindings
When compiled with the symbol AGL_DEVEL defined, the ***binder***
-understand the 2 configuration variables:
+understands the 2 configuration variables:
- AFB_DEBUG_BREAK: to emit interrupts
- AFB_DEBUG_WAIT: to wait interrupts
The items of the list can be separated using comma, space, tab or new-line.
-The break/wait points are, in the order of their occurence:
+The break/wait points are, in the order of their occurrence:
- main-entry: before decode arguments
- main-args: before daemon setup
instance.
It implements an API and may provide a service.
-Binding made for services can have specific entry point called after
+Binding made for services can have specific entry points called after
initialization and before serving.
## Event
-Message with data propagated from the services to the client and not expecting
+Messages with data propagated from the services to the client and not expecting
any reply.
The current implementation allows to widely broadcast events to all clients.
# Desktop packages for binder development
-It exists packages of the ***binder*** (afb-daemon)
+Packages of the ***binder*** (afb-daemon)exist
for common desktop linux distributions.
- Fedora
# Guide for developing with events
Signaling agents are services that send events to any clients that
-subscribed for receiving it.
+are subscribed to receive it.
The sent events carry any data.
To have a good understanding of how to:
Subscription must :
1. Create resources for generating the data.
-1. Delivering the data to the client.
+1. Deliver the data to the client.
These two aspects are not handled by the same piece of software.
When a client subscribes for data, the agent must:
-1. check that the subscription request is correct.
-1. establish the computation chain of the required data (if not already done).
-1. create a named event for the computed data (if not already done).
-1. ask the framework to establish the subscription to the event for the request.
-1. optionally give indications about the event in the reply to the client.
+1. Check that the subscription request is correct.
+1. Establish the computation chain of the required data (if not already done).
+1. Create a named event for the computed data (if not already done).
+1. Ask the framework to establish the subscription to the event for the request.
+1. Optionally give indications about the event in the reply to the client.
-The first two steps are not involving the framework.
+The first two steps do not involve the framework.
They are linked to the business logic of the binding.
The request can be any description of the requested data
and the computing stream can be of any nature,
### Event handlers
-The apis functions allow to declare event handling callbacks. These callback are
+The apis functions allow to declare event handling callbacks. These callbacks are
called on reception of an event matching a pattern and a receive in more that
the event name and its companion JSON data, a user defiend closure and the api
that is used to create it.
- integration of the security requirements within the bindings
- simplification of the API (after developer feedbacks)
-- removal of obscure features, cleanup
+- removal of obscure features and cleanup
The ***binder*** can run ***bindings*** v1, v2 and/or v3 in any combination.
Thus moving from v1 or v2 to v3 is not enforced at this time. But ...
-In the face to face meeting of Karlsruhe it was decided to remove support
+In the face to face meeting in Karlsruhe it was decided to remove support
of bindings v1 and to deprecate the use of bindings v2.
So at the end, **IT IS HIGHLY NEEDED TO SWITCH TO VERSION 3**
This guide covers the migration of bindings from version 2 to version 3.
The migration from version 1 is not treated here because bindings version 1
-are very old and probably does not exist anymore. If needed you can refer
+are very old and probably do not exist anymore. If needed you can refer
to the old [guide to migrate bindings from v1 to v2](legacy/afb-migration-v1-to-v2.html).
- The SECURITY CONTEXT
- The primary intend of any ***binder*** is to provide
+ The primary intention of any ***binder*** is to provide
a secured environment for any application.
On AGL, the **security context** is ensured by [Smack]
, the security context of the application or service.
```C
/**
* Check that it requires the API of 'name'.
- * If 'initialized' is not zero it request the API to be
+ * If 'initialized' is not zero it requests the API to be
* initialized, implying its initialization if needed.
*
* Calling this function is only allowed within init.
* Get the root directory file descriptor. This file descriptor can
* be used with functions 'openat', 'fstatat', ...
*
- * CAUTION, manipulate this this descriptor with care, in particular, don't close
+ * CAUTION, manipulate this descriptor with care, in particular, don't close
* it.
*
* This can be used to get the path of the root directory using:
*
* Makes a call to the method of name 'api' / 'verb' with the object 'args'.
* This call is made in the context of the request 'req'.
- * This call is synchronous, it waits untill completion of the request.
+ * This call is synchronous, it waits until completion of the request.
* It returns 0 on success or a negative value on error answer.
* The object pointed by 'result' is filled and must be released by the caller
* after its use by calling 'json_object_put'.
==============================
All the functions of the class **afb_daemon** use the default api.
-This are internally aliased to the corresponding legacy function of
+These are internally aliased to the corresponding legacy function of
class **afb_api**.
```C
## The global afbBindingRoot
-The global **afbBindingRoot** of type **afb_api_t** is always implicitely
+The global **afbBindingRoot** of type **afb_api_t** is always implicitly
defined for bindings of version 3 or upper. It records the root api of
the binding.
Code Review / src / app-framework-binder.git / commitdiff