diff options
| -rw-r--r-- | docs/FAQ.md | 6 | ||||
| -rw-r--r-- | docs/afb-application-writing.md | 230 | ||||
| -rw-r--r-- | docs/afb-binding-references.md | 131 | ||||
| -rw-r--r-- | docs/afb-binding-writing.md | 91 | ||||
| -rw-r--r-- | docs/afb-daemon-options.md | 218 | ||||
| -rw-r--r-- | docs/afb-daemon-vocabulary.md | 52 | ||||
| -rw-r--r-- | docs/afb-desktop-package.md | 36 | ||||
| -rw-r--r-- | docs/afb-events-guide.md | 275 | ||||
| -rw-r--r-- | docs/afb-migration-v1-to-v2.md | 279 | ||||
| -rw-r--r-- | docs/afb-overview.md | 72 | ||||
| -rw-r--r-- | docs/annexes.md | 7 |
11 files changed, 741 insertions, 656 deletions
diff --git a/docs/FAQ.md b/docs/FAQ.md index 5063ed74..e80bfe85 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,5 +1 @@ -Frequently Asked Question about AFB-DAEMON -========================================== - - - +# Frequently Asked Question about AFB-DAEMON diff --git a/docs/afb-application-writing.md b/docs/afb-application-writing.md index cc513b48..cfce7179 100644 --- a/docs/afb-application-writing.md +++ b/docs/afb-application-writing.md @@ -1,8 +1,6 @@ -How to write an application on top of AGL FRAMEWORK -==================================================== +# How to write an application on top of AGL FRAMEWORK -Programming Languages for Applications ------------------------------------------ +## Programming Languages for Applications ### Writing an HTML5 application @@ -11,7 +9,8 @@ applications for AGL framework using their preferred HTML5 framework. Developers may also take advantage of powerful server side bindings to improve -application behavior. Server side bindings return an application/json mine-type +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 the current @@ -25,14 +24,15 @@ Two examples of HTML5 applications are given: ### 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 available: +It is also possible to write QML applications. +A sample QML application [token-websock] is available: - [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 + +A simple "hello world" application in QML ### Writing a "C" application @@ -42,30 +42,30 @@ 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 -**libafbwsc** library. +**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. +Current implementation relies on libsystemd and file descriptors. This model might be review in the future to support secure sockets and get rid of libsystemd dependency. -Handling sessions within applications -------------------------------------- +### Handling sessions within applications Applications should understand sessions and token management when interacting with afb-daemon binder. -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 +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 -of client is named "session". +by using a shared secret. +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. @@ -73,24 +73,27 @@ how authentication and sessions are managed. ### Handling sessions Bindings and other binder features need to keep track of client -instances. This is especially important for bindings running as services +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 +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 -the access to some binding's methods. +token for session management. +This authentication token can be use to restrict 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**. @@ -102,7 +105,9 @@ To ensure security, tokens must be refreshed periodically. In following examples, we suppose that **afb-daemon** is launched with something equivalent to: - $ afb-daemon --port=1234 --token=123456 [...] +```bash +afb-daemon --port=1234 --token=123456 [...] +``` making the expectation that **AuthLogin** binding is requested as default. @@ -110,102 +115,117 @@ making the expectation that **AuthLogin** binding is requested as default. First, connects with the initial token, 123456: - $ curl http://localhost:1234/api/auth/connect?token=123456 - { - "jtype": "afb-reply", - "request": { - "status": "success", - "token": "0aef6841-2ddd-436d-b961-ae78da3b5c5f", - "uuid": "850c4594-1be1-4e9b-9fcc-38cc3e6ff015" - }, - "response": {"token": "A New Token and Session Context Was Created"} - } +```bash +$ curl http://localhost:1234/api/auth/connect?token=123456 +{ + "jtype": "afb-reply", + "request": { + "status": "success", + "token": "0aef6841-2ddd-436d-b961-ae78da3b5c5f", + "uuid": "850c4594-1be1-4e9b-9fcc-38cc3e6ff015" + }, + "response": {"token": "A New Token and Session Context Was Created"} +} +``` It returns an answer containing session UUID, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015, and a refreshed token, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015. Check if session and token is valid: - $ curl http://localhost:1234/api/auth/check?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 - { - "jtype": "afb-reply", - "request": {"status":"success"}, - "response": {"isvalid":true} - } +```bash +$ curl http://localhost:1234/api/auth/check?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 +{ + "jtype": "afb-reply", + "request": {"status":"success"}, + "response": {"isvalid":true} +} +``` Refresh the token: - $ curl http://localhost:1234/api/auth/refresh?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 - { - "jtype": "afb-reply", - "request": { - "status":"success", - "token":"b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9" - }, - "response": {"token":"Token was refreshed"} - } +```bash +$ curl http://localhost:1234/api/auth/refresh?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 +{ + "jtype": "afb-reply", + "request": { + "status":"success", + "token":"b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9" + }, + "response": {"token":"Token was refreshed"} +} +``` Close the session: - curl http://localhost:1234/api/auth/logout?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 - { - "jtype": "afb-reply", - "request": {"status": "success"}, - "response": {"info":"Token and all resources are released"} - } +```bash +$ curl http://localhost:1234/api/auth/logout?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 +{ + "jtype": "afb-reply", + "request": {"status": "success"}, + "response": {"info":"Token and all resources are released"} +} +``` Checking on closed session for uuid should be refused: - curl http://localhost:1234/api/auth/check?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 - { - "jtype": "afb-reply", - "request": { - "status": "failed", - "info": "invalid token's identity" - } - } +```bash +$ curl http://localhost:1234/api/auth/check?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 +{ + "jtype": "afb-reply", + "request": { + "status": "failed", + "info": "invalid token's identity" + } +} +``` #### Using afb-client-demo -> The program is packaged within AGL in the rpm **libafbwsc-dev** +- 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 - auth connect - ON-REPLY 1:auth/connect: {"jtype":"afb-reply","request":{"status":"success", - "token":"63f71a29-8b52-4f9b-829f-b3028ba46b68","uuid":"5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1"}, - "response":{"token":"A New Token and Session Context Was Created"}} - auth check - ON-REPLY 2:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} - auth refresh - ON-REPLY 4:auth/refresh: {"jtype":"afb-reply","request":{"status":"success", - "token":"8b8ba8f4-1b0c-48fa-962d-4a00a8c9157e"},"response":{"token":"Token was refreshed"}} - auth check - ON-REPLY 5:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} - auth refresh - ON-REPLY 6:auth/refresh: {"jtype":"afb-reply","request":{"status":"success", - "token":"e83b36f8-d945-463d-b983-5d8ed73ba529"},"response":{"token":"Token was refreshed"}} +```bash +$ afb-client-demo ws://localhost:1234/api?token=123456 +auth connect +ON-REPLY 1:auth/connect: {"jtype":"afb-reply","request":{"status":"success", + "token":"63f71a29-8b52-4f9b-829f-b3028ba46b68","uuid":"5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1"}, + "response":{"token":"A New Token and Session Context Was Created"}} +auth check +ON-REPLY 2:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} +auth refresh +ON-REPLY 4:auth/refresh: {"jtype":"afb-reply","request":{"status":"success", + "token":"8b8ba8f4-1b0c-48fa-962d-4a00a8c9157e"},"response":{"token":"Token was refreshed"}} +auth check +ON-REPLY 5:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} +auth refresh +ON-REPLY 6:auth/refresh: {"jtype":"afb-reply","request":{"status":"success", + "token":"e83b36f8-d945-463d-b983-5d8ed73ba529"},"response":{"token":"Token was refreshed"}} +``` After closing connection, reconnect as here after: - $ afb-client-demo ws://localhost:1234/api?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1 auth check - ON-REPLY 1:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} +```bash +$ afb-client-demo ws://localhost:1234/api?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1 auth check +ON-REPLY 1:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} +``` Same connection check using **curl**: - $ curl http://localhost:1234/api/auth/check?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1 - {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} +```bash +$ curl http://localhost:1234/api/auth/check?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1 +{"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} +``` -Format of replies ------------------ +### Format of replies 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**. -### Template +#### Template of replies This is a template of replies: @@ -223,55 +243,54 @@ This is a template of replies: } ``` -### Field jtype +#### Field jtype of replies The field **jtype** must have a value of type string equal to **"afb-reply"**. -### Field request +#### Field request of replies -The field **request** must have a value of type object. This request object -has at least one field named **status** and four optional fields named -**info**, **token**, **uuid**, **reqid**. +The field **request** must have a value of type object. +This request object has at least one field named **status** +and four optional fields named **info**, **token**, **uuid**, **reqid**. -#### Subfield request.status +##### Subfield request.status **status** must have a value of type string. This string is equal to **"success"** only in case of success. -#### Subfield request.info +##### Subfield request.info **info** is of type string and represent optional information added to the reply. -#### Subfield request.token +##### Subfield request.token **token** is of type string. It is sent either at session creation or when the token is refreshed. -#### Subfield request.uuid +##### Subfield request.uuid **uuid** is of type string. It is sent at session creation. -#### Subfield request.reqid +##### Subfield request.reqid **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. -### Field response +#### Field response of replies This field response optionally contains an object returned when request succeeded. -Format of events ----------------- +### 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 +#### Template of event Here is a template of event: @@ -283,11 +302,11 @@ Here is a template of event: } ``` -### Field jtype +#### Field jtype of event The field **jtype** must have a value of type string equal to **"afb-event"**. -### Field event +#### Field event of event The field **event** carries the event's name. @@ -295,7 +314,6 @@ 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 +#### Field data of event This field data if present holds the data carried by the event. - diff --git a/docs/afb-binding-references.md b/docs/afb-binding-references.md index a90adf36..97ed14a7 100644 --- a/docs/afb-binding-references.md +++ b/docs/afb-binding-references.md @@ -1,8 +1,6 @@ -Binding Reference -================= +# Binding Reference -Structure for declaring binding -------------------------------- +## Structure for declaring binding ### struct afb_binding_v2 @@ -17,14 +15,14 @@ This structure is defined as below. */ struct afb_binding_v2 { - const char *api; /* api name for the binding */ - const char *specification; /* textual openAPIv3 specification of the binding */ - const char *info; /* some info about the api, can be NULL */ - const struct afb_verb_v2 *verbs; /* array of descriptions of verbs terminated by a NULL name */ + const char *api; /* api name for the binding */ + const char *specification; /* textual openAPIv3 specification of the binding */ + const char *info; /* some info about the api, can be NULL */ + const struct afb_verb_v2 *verbs; /* array of descriptions of verbs terminated by a NULL name */ int (*preinit)(); /* callback at load of the binding */ int (*init)(); /* callback for starting the service */ void (*onevent)(const char *event, struct json_object *object); /* callback for handling events */ - unsigned noconcurrency: 1; /* avoids concurrent requests to verbs */ + unsigned noconcurrency: 1; /* avoids concurrent requests to verbs */ }; ``` @@ -42,30 +40,30 @@ struct afb_verb_v2 { const char *verb; /* name of the verb */ void (*callback)(struct afb_req req); /* callback function implementing the verb */ - const struct afb_auth *auth; /* required authorization */ - const char *info; /* some info about the verb, can be NULL */ + const struct afb_auth *auth; /* required authorization */ + const char *info; /* some info about the verb, can be NULL */ uint32_t session; /* authorization and session requirements of the verb */ }; ``` -The session flags is an or of the constant defined below: +The **session** flags is one of the constant defined below: - - AFB_SESSION_NONE : no flag, synonym to 0 - - AFB_SESSION_LOA_0 : Requires the LOA to be 0 or more, synonym to 0 or AFB_SESSION_NONE - - AFB_SESSION_LOA_1 : Requires the LOA to be 1 or more - - AFB_SESSION_LOA_2 : Requires the LOA to be 2 or more - - AFB_SESSION_LOA_3 : Requires the LOA to be 3 or more - - AFB_SESSION_CHECK : Requires the token to be set and valid - - AFB_SESSION_REFRESH : Implies a token refresh - - AFB_SESSION_CLOSE : Implies cloing the session +- AFB_SESSION_NONE : no flag, synonym to 0 +- AFB_SESSION_LOA_0 : Requires the LOA to be 0 or more, synonym to 0 or AFB_SESSION_NONE +- AFB_SESSION_LOA_1 : Requires the LOA to be 1 or more +- AFB_SESSION_LOA_2 : Requires the LOA to be 2 or more +- AFB_SESSION_LOA_3 : Requires the LOA to be 3 or more +- AFB_SESSION_CHECK : Requires the token to be set and valid +- AFB_SESSION_REFRESH : Implies a token refresh +- AFB_SESSION_CLOSE : Implies cloing the session -The LOA is set binding by binding using the function **afb_req_session_set_LOA**. +The LOA (Level Of Assurance) is set, by binding, using the function **afb_req_session_set_LOA**. ### struct afb_auth and enum afb_auth_type The structure **afb_auth** is used within verb description to -set security requirements. The interpretation of the structure -depends on the value of the field **type**. +set security requirements. +The interpretation of the structure depends on the value of the field **type**. ```C struct afb_auth @@ -79,6 +77,7 @@ struct afb_auth const struct afb_auth *next; }; ``` + The possible values for **type** is defined here: ```C @@ -87,14 +86,14 @@ The possible values for **type** is defined here: */ enum afb_auth_type { - afb_auth_No = 0, /** never authorized, no data */ - afb_auth_Token, /** authorized if token valid, no data */ - afb_auth_LOA, /** authorized if LOA greater than data 'loa' */ - afb_auth_Permission, /** authorized if permission 'text' is granted */ - afb_auth_Or, /** authorized if 'first' or 'next' is authorized */ - afb_auth_And, /** authorized if 'first' and 'next' are authorized */ - afb_auth_Not, /** authorized if 'first' is not authorized */ - afb_auth_Yes /** always authorized, no data */ + afb_auth_No = 0, /** never authorized, no data */ + afb_auth_Token, /** authorized if token valid, no data */ + afb_auth_LOA, /** authorized if LOA greater than data 'loa' */ + afb_auth_Permission, /** authorized if permission 'text' is granted */ + afb_auth_Or, /** authorized if 'first' or 'next' is authorized */ + afb_auth_And, /** authorized if 'first' and 'next' are authorized */ + afb_auth_Not, /** authorized if 'first' is not authorized */ + afb_auth_Yes /** always authorized, no data */ }; ``` @@ -102,16 +101,15 @@ Example: ```C static const struct afb_auth _afb_auths_v2_monitor[] = { - { .type = afb_auth_Permission, .text = "urn:AGL:permission:monitor:public:set" }, - { .type = afb_auth_Permission, .text = "urn:AGL:permission:monitor:public:get" }, - { .type = afb_auth_Or, .first = &_afb_auths_v2_monitor[1], .next = &_afb_auths_v2_monitor[0] } + { .type = afb_auth_Permission, .text = "urn:AGL:permission:monitor:public:set" }, + { .type = afb_auth_Permission, .text = "urn:AGL:permission:monitor:public:get" }, + { .type = afb_auth_Or, .first = &_afb_auths_v2_monitor[1], .next = &_afb_auths_v2_monitor[0] } }; ``` -Functions of class afb_daemon... -------------------------- +## Functions of class afb_daemon -The 3 following functions are linked to libsystemd. +The 3 following functions are linked to libsystemd. They allow use of **sd_event** features and access to **sd_bus** features. @@ -132,7 +130,7 @@ struct sd_bus *afb_daemon_get_user_bus(); struct sd_bus *afb_daemon_get_system_bus(); ``` -The 2 following functions are linked to event management. +The 2 following functions are linked to event management. Broadcasting an event send it to any possible listener. ```C @@ -157,9 +155,14 @@ struct afb_event afb_daemon_make_event(const char *name); ``` The following function is used by logging macros and should normally -not be used. Instead, you should use the macros -**AFB\_ERROR**, **AFB\_WARNING**, **AFB\_NOTICE**, -**AFB\_INFO**, **AFB\_DEBUG** +not be used. +Instead, you should use the macros: + +- **AFB\_ERROR** +- **AFB\_WARNING** +- **AFB\_NOTICE** +- **AFB\_INFO** +- **AFB\_DEBUG** ```C /* @@ -230,8 +233,7 @@ bindings at its initialization. int afb_daemon_require_api(const char *name, int initialized) ``` -Functions of class afb_service... -------------------------- +## Functions of class afb_service The following functions allow services to call verbs of other bindings for themselves. @@ -259,11 +261,11 @@ bindings for themselves. * @see also 'afb_req_subcall' */ void afb_service_call( - const char *api, - const char *verb, - struct json_object *args, - void (*callback)(void*closure, int status, struct json_object *result), - void *callback_closure); + const char *api, + const char *verb, + struct json_object *args, + void (*callback)(void*closure, int status, struct json_object *result), + void *callback_closure); /** * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. @@ -283,17 +285,16 @@ void afb_service_call( * @see also 'afb_req_subcall' */ int afb_service_call_sync( - const char *api, - const char *verb, - struct json_object *args, - struct json_object **result); + const char *api, + const char *verb, + struct json_object *args, + struct json_object **result); ``` -Functions of class afb_event... -------------------------- +## Functions of class afb_event -This function checks whether the event is valid. It must be used -when creating events. +This function checks whether the event is valid. +It must be used when creating events. ```C /* @@ -353,8 +354,7 @@ This function allows to retrieve the exact name of the event. const char *afb_event_name(struct afb_event event); ``` -Functions of class afb_req... -------------------------- +## Functions of class afb_req This function checks the validity of the **req**. @@ -516,7 +516,6 @@ void afb_req_session_close(struct afb_req req); int afb_req_session_set_LOA(struct afb_req req, unsigned level); ``` - The 4 following functions must be used for asynchronous handling requests. ```C @@ -617,9 +616,14 @@ int afb_req_subcall_sync( ``` The following function is used by logging macros and should normally -not be used. Instead, you should use the macros -**AFB_REQ_ERROR**, **AFB_REQ_WARNING**, **AFB_REQ_NOTICE**, -**AFB_REQ_INFO**, **AFB_REQ_DEBUG** +not be used. +Instead, you should use the macros: + +- **AFB_REQ_ERROR** +- **AFB_REQ_WARNING** +- **AFB_REQ_NOTICE** +- **AFB_REQ_INFO** +- **AFB_REQ_DEBUG** ```C /* @@ -642,8 +646,7 @@ not be used. Instead, you should use the macros void afb_req_verbose(struct afb_req req, int level, const char *file, int line, const char * func, const char *fmt, ...); ``` -Logging macros --------------- +## Logging macros The following macros must be used for logging: diff --git a/docs/afb-binding-writing.md b/docs/afb-binding-writing.md index ceb80a87..aad422c4 100644 --- a/docs/afb-binding-writing.md +++ b/docs/afb-binding-writing.md @@ -1,12 +1,10 @@ - -Overview of the bindings -======================== +# 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 WebSocket protocol. -The ***bindings*** are used to add **API** to ***binders***. +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. @@ -16,19 +14,20 @@ 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. +desktop used for writing the binding. +It allows easy debug and test. ## Nature of a binding A ***binding*** is an independent piece of software compiled as a shared -library and dynamically loaded by a ***binder***. +library and dynamically loaded by a ***binder***. It is intended to provide one **API** (**A**pplication **P**rogramming **I**nterface). -The **API** is designated and accessed through its name. +The **API** is designated and accessed through its name. It contains several **verbs** that implement the ***binding*** -functionalities. Each of these **verbs** is a **method** that +functionalities. +Each of these **verbs** is a **method** that processes requests of applications and sends result. The ***binding***'s methods are invoked by HTTP or websocket @@ -36,34 +35,34 @@ requests. The **methods** of the ***bindings*** are noted **api/verb** where **api** is the **API** name of the binding and **verb** is -the **method**'s name within the **API**. +the **method**'s name within the **API**. This notation comes from HTTP invocations that rely on URL path terminated with **api/verb**. The name of an **API** can be made of any characters except: - - the control characters (\u0000 .. \u001f) - - the characters of the set { ' ', '"', '#', '%', '&', +- the control characters (\u0000 .. \u001f) +- the characters of the set { ' ', '"', '#', '%', '&', '\'', '/', '?', '`', '\x7f' } -The names if the **verbs** can be any character. +The names of the **verbs** can be any character. The binder makes no distinctions between upper case and lower case -latin letters. So **API/VERB** matches **Api/Verb** or **api/verb**. +latin letters. +So **API/VERB** matches **Api/Verb** or **api/verb**. Actually it exists 2 ways of writing ***bindings***. You can either write: - - a binding version 1 (not recommended); - - a binding version 2 (RECOMMENDED). +- a binding version 1 (not recommended); +- a binding version 2 (RECOMMENDED). -A ***binder*** loads and runs any of these version in any combination. +A ***binder*** loads and runs any of these version in any combination. This document explain how to write bindings version 2. <!-- pagebreak --> -Sample binding: tuto-1 -====================== +## Sample binding: tuto-1 This is the code of the binding **tuto-1.c**: @@ -91,13 +90,13 @@ This is the code of the binding **tuto-1.c**: Compiling: ```bash -$ gcc -fPIC -shared tuto-1.c -o tuto-1.so $(pkg-config --cflags-only-I afb-daemon) +gcc -fPIC -shared tuto-1.c -o tuto-1.so $(pkg-config --cflags-only-I afb-daemon) ``` Running: ```bash -$ afb-daemon --binding tuto-1.so --port 3333 --token '' +afb-daemon --binding tuto-1.so --port 3333 --token '' ``` Testing using **curl**: @@ -125,10 +124,9 @@ ON-REPLY 1:tuto-1/hello: OK This shows basic things: - - 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 - +- 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 ### Getting declarations for the binding @@ -139,12 +137,12 @@ The lines 1 and 2 show how to get the include file **afb-binding.h**. 2 #include <afb/afb-binding.h> ``` -You must define the version of ***binding*** that you are using. +You must define the version of ***binding*** that you are using. This is done line 1 where we define that this is the version 2. If you don't define it, a warning message is prompted by the compiler -and the version is switched to version 1. This behaviour is -temporarily and enables to continue to use previously written +and the version is switched to version 1. +This behaviour is temporarily and enables to continue to use previously written ***binding*** without change but it will change in some future when ***bindings*** V1 will become obsoletes. @@ -155,13 +153,15 @@ should be set correctly if needed (not needed only if installed in Setting the include path is easy using **pkg-config**: ```bash -$ pkg-config --cflags-only-I afb-daemon +pkg-config --cflags-only-I afb-daemon ``` -Note for **C++** developers: The ***binder*** currently expose -only **C** language **API**. The file **afb/afb-binding.h** -isn't **C++** ready. You should use the construct **extern "C"** -as below: +Note for **C++** developers: + +- The ***binder*** currently expose only **C** language **API**. + The file **afb/afb-binding.h** isn't **C++** ready. + +You should use the construct **extern "C"** as below: ```C #define AFB_BINDING_VERSION 2 @@ -171,8 +171,8 @@ as below: ``` Future version of the ***binder*** will include a **C++** -interface. Until it is available, please, use the above -construct. +interface. +Until it is available, please, use the above construct. ### Declaring the API of the binding @@ -196,8 +196,8 @@ a structure of type **afb_binding_v2**. The structure **afbBindingV2** actually tells that: - - the exported **API** name is **tuto-1** (line 16) - - the array of verbs is the above defined one +- the exported **API** name is **tuto-1** (line 16) +- the array of verbs is the above defined one The exported list of verb is specified by an array of structures, each describing a verb, ended with a verb NULL (line 12). @@ -242,8 +242,8 @@ The callback has to treat synchronously or asynchronously the request and should at the end emit a reply for the request. Here, the callback for **tuto-1/hello** replies a successful answer -(line 7) to the request **req**. The second parameter (here NULL) -is a json object that is sent to the client with the reply. +(line 7) to the request **req**. +The second parameter (here NULL) is a json object that is sent to the client with the reply. The third parameter is also sent with the reply and is a string called info that can be used as some meta data. @@ -256,12 +256,12 @@ Here again, you can explicitly mark the fact that <!-- pagebreak --> -Sample binding: tuto-2 -====================== +## Sample binding: tuto-2 The second tutorial shows many important feature that can -commonly be used when writing a ***binding***: initialization, -getting arguments, sending replies, pushing events. +commonly be used when writing a ***binding***: + +- initialization, getting arguments, sending replies, pushing events. This is the code of the binding **tuto-2.c**: @@ -371,13 +371,13 @@ This is the code of the binding **tuto-2.c**: Compiling: ```bash -$ gcc -fPIC -shared tuto-2.c -o tuto-2.so $(pkg-config --cflags --libs afb-daemon) +gcc -fPIC -shared tuto-2.c -o tuto-2.so $(pkg-config --cflags --libs afb-daemon) ``` Running: ```bash -$ afb-daemon --binding tuto-2.so --port 3333 --token '' +afb-daemon --binding tuto-2.so --port 3333 --token '' ``` Testing: @@ -461,4 +461,3 @@ ON-EVENT tuto-2/logout: "jtype":"afb-event" } ``` - diff --git a/docs/afb-daemon-options.md b/docs/afb-daemon-options.md index 84f7ce98..28aff6b2 100644 --- a/docs/afb-daemon-options.md +++ b/docs/afb-daemon-options.md @@ -1,200 +1,198 @@ - -Launching options of afb-daemon ---------------------- +# Launching options of afb-daemon The launch options for binder **afb-daemon** are: - --help + --help - Prints help with available options + Prints help with available options - --version + --version - Display version and copyright + Display version and copyright - --verbose + --verbose - Increases the verbosity, can be repeated + Increases the verbosity, can be repeated - --quiet + --quiet - Decreases the verbosity, can be repeated + Decreases the verbosity, can be repeated - --port=xxxx + --port=xxxx - HTTP listening TCP port [default 1234] + HTTP listening TCP port [default 1234] - --workdir=xxxx + --workdir=xxxx - Directory where the daemon must run [default: $PWD if defined - or the current working directory] + Directory where the daemon must run [default: $PWD if defined + or the current working directory] - --uploaddir=xxxx + --uploaddir=xxxx - Directory where uploaded files are temporarily stored [default: workdir] + Directory where uploaded files are temporarily stored [default: workdir] - --rootdir=xxxx + --rootdir=xxxx - Root directory of the application to serve [default: workdir] + Root directory of the application to serve [default: workdir] - --roothttp=xxxx + --roothttp=xxxx - Directory of HTTP served files. If not set, files are not served - but apis are still accessible. + Directory of HTTP served files. If not set, files are not served + but apis are still accessible. - --rootbase=xxxx + --rootbase=xxxx - Angular Base Root URL [default /opa] + Angular Base Root URL [default /opa] - This is used for any application of kind OPA (one page application). - When set, any missing document whose url has the form /opa/zzz - is translated to /opa/#!zzz + This is used for any application of kind OPA (one page application). + When set, any missing document whose url has the form /opa/zzz + is translated to /opa/#!zzz - --rootapi=xxxx + --rootapi=xxxx - HTML Root API URL [default /api] + HTML Root API URL [default /api] - The bindings are available within that url. + The bindings are available within that url. - --alias=xxxx + --alias=xxxx - Maps a path located anywhere in the file system to the - a subdirectory. The syntax for mapping a PATH to the - subdirectory NAME is: --alias=/NAME:PATH. + Maps a path located anywhere in the file system to the + a subdirectory. The syntax for mapping a PATH to the + subdirectory NAME is: --alias=/NAME:PATH. - Example: --alias=/icons:/usr/share/icons maps the - content of /usr/share/icons within the subpath /icons. + Example: --alias=/icons:/usr/share/icons maps the + content of /usr/share/icons within the subpath /icons. - This option can be repeated. + This option can be repeated. - --apitimeout=xxxx + --apitimeout=xxxx - binding API timeout in seconds [default 20] + binding API timeout in seconds [default 20] - Defines how many seconds maximum a method is allowed to run. - 0 means no limit. + Defines how many seconds maximum a method is allowed to run. + 0 means no limit. - --cntxtimeout=xxxx + --cntxtimeout=xxxx - Client Session Timeout in seconds [default 3600] + Client Session Timeout in seconds [default 3600] - --cache-eol=xxxx + --cache-eol=xxxx - Client cache end of live [default 100000 that is 27,7 hours] + Client cache end of live [default 100000 that is 27,7 hours] - --session-max=xxxx + --session-max=xxxx - Maximum count of simultaneous sessions [default 10] + Maximum count of simultaneous sessions [default 10] - --ldpaths=xxxx + --ldpaths=xxxx - Load bindings from given paths separated by colons - as for dir1:dir2:binding1.so:... [default = $libdir/afb] + Load bindings from given paths separated by colons + as for dir1:dir2:binding1.so:... [default = $libdir/afb] - You can mix path to directories and to bindings. - The sub-directories of the given directories are searched - recursively. + You can mix path to directories and to bindings. + The sub-directories of the given directories are searched + recursively. - The bindings are the files terminated by '.so' (the extension - so denotes shared object) that contain the public entry symbol. + The bindings are the files terminated by '.so' (the extension + so denotes shared object) that contain the public entry symbol. - --binding=xxxx + --binding=xxxx - Load the binding of given path. + Load the binding of given path. - --token=xxxx + --token=xxxx - Initial Secret token to authenticate. + Initial Secret token to authenticate. - If not set, no client can authenticate. + If not set, no client can authenticate. - If set to the empty string, then any initial token is accepted. + If set to the empty string, then any initial token is accepted. - --random-token + --random-token - Generate a random starting token. See option --exec. + Generate a random starting token. See option --exec. - --mode=xxxx + --mode=xxxx - Set the mode: either local, remote or global. + Set the mode: either local, remote or global. - The mode indicate if the application is run locally on the host - or remotely through network. + The mode indicate if the application is run locally on the host + or remotely through network. - --dbus-client=xxxx + --dbus-client=xxxx - Transparent binding to a binder afb-daemon service through dbus. + Transparent binding to a binder afb-daemon service through dbus. - It creates an API of name xxxx that is implemented remotely - and queried via DBUS. + It creates an API of name xxxx that is implemented remotely + and queried via DBUS. - --dbus-server=xxxx + --dbus-server=xxxx - Provides a binder afb-daemon service through dbus. + Provides a binder afb-daemon service through dbus. - The name xxxx must be the name of an API defined by a binding. - This API is exported through DBUS. + The name xxxx must be the name of an API defined by a binding. + This API is exported through DBUS. - --ws-client=xxxx + --ws-client=xxxx - Transparent binding to a binder afb-daemon service through a WebSocket. + Transparent binding to a binder afb-daemon service through a WebSocket. - The value of xxxx is either a unix naming socket, of the form "unix:path/api", - or an internet socket, of the form "host:port/api". + The value of xxxx is either a unix naming socket, of the form "unix:path/api", + or an internet socket, of the form "host:port/api". - --ws-server=xxxx + --ws-server=xxxx - Provides a binder afb-daemon service through WebSocket. + Provides a binder afb-daemon service through WebSocket. - The value of xxxx is either a unix naming socket, of the form "unix:path/api", - or an internet socket, of the form "host:port/api". + The value of xxxx is either a unix naming socket, of the form "unix:path/api", + or an internet socket, of the form "host:port/api". - --foreground + --foreground - Get all in foreground mode (default) + Get all in foreground mode (default) - --daemon + --daemon - Get all in background mode + Get all in background mode - --no-httpd + --no-httpd - Forbids HTTP serve + Forbids HTTP serve - --exec + --exec - Must be the last option for afb-daemon. The remaining - arguments define a command that afb-daemon will launch. - The sequences @p, @t and @@ of the arguments are replaced - with the port, the token and @. + Must be the last option for afb-daemon. The remaining + arguments define a command that afb-daemon will launch. + The sequences @p, @t and @@ of the arguments are replaced + with the port, the token and @. - --tracereq=xxxx + --tracereq=xxxx - Trace the processing of requests in the log file. + Trace the processing of requests in the log file. - Valid values are 'no' (default), 'common', 'extra' or 'all'. + Valid values are 'no' (default), 'common', 'extra' or 'all'. - --traceditf=xxxx + --traceditf=xxxx - Trace the accesses to functions of class daemon. + Trace the accesses to functions of class daemon. - Valid values are 'no' (default), 'common', 'extra' or 'all'. + Valid values are 'no' (default), 'common', 'extra' or 'all'. - --tracesvc=xxxx + --tracesvc=xxxx - Trace the accesses to functions of class service. + Trace the accesses to functions of class service. - Valid values are 'no' (default) or 'all'. + Valid values are 'no' (default) or 'all'. - --traceevt=xxxx + --traceevt=xxxx - Trace the accesses to functions of class event. + Trace the accesses to functions of class event. - Valid values are 'no' (default), 'common', 'extra' or 'all'. + Valid values are 'no' (default), 'common', 'extra' or 'all'. --call=xxx - Call a binding at start (can be be repeated). - The values are given in the form API/VERB:json-args. + Call a binding at start (can be be repeated). + The values are given in the form API/VERB:json-args. - Example: --call 'monitor/set:{"verbosity":{"api":"debug"}}' + Example: --call 'monitor/set:{"verbosity":{"api":"debug"}}' diff --git a/docs/afb-daemon-vocabulary.md b/docs/afb-daemon-vocabulary.md index c343abdc..6c51f124 100644 --- a/docs/afb-daemon-vocabulary.md +++ b/docs/afb-daemon-vocabulary.md @@ -1,11 +1,10 @@ - -Vocabulary for AFB-DAEMON -========================= +# Vocabulary for AFB-DAEMON ## Binding A shared library object intended to add a functionality to an afb-daemon -instance. It implements an API and may provide a service. +instance. +It implements an API and may provide a service. Binding made for services can have specific entry point called after initialization and before serving. @@ -32,8 +31,14 @@ Old name for binding, see binding. ## Request A request is an invocation by a client to a binding method using a message -transferred through some protocol: HTTP, WebSocket, DBUS... and served by -***afb-daemon*** +transferred through some protocol: + +- HTTP +- WebSocket +- DBUS +- ... + +and served by ***afb-daemon*** ## Reply/Response @@ -41,21 +46,22 @@ This is a message sent to client as the result of the request. ## Service -Service are made of bindings running by their side on their binder. -It can serve many client. Each one attached to one session. +Service are made of bindings running by their side on their binder. +It can serve many client. +Each one attached to one session. -The framework establishes connection between the services and -the clients. Using DBus currently but other protocols are considered. +The framework establishes connection between the services and the clients. +Using DBus currently but other protocols are considered. ## Session A session is meant to be the unique instance context of a client, which identify that instance across requests. -Each session has an identifier. Session identifier generated by afb-daemon are -UUIDs. +Each session has an identifier. +Session identifier generated by afb-daemon are UUIDs. -Internally, afb-daemon offers a mechanism to attach data to sessions. +Internally, afb-daemon offers a mechanism to attach data to sessions. When the session is closed or disappears, the data attached to that session are freed. @@ -63,13 +69,13 @@ are freed. The token is an identifier that the client must give to be authenticated. -At start, afb-daemon get an initial token. This initial token must be presented -by incoming client to be authenticated. +At start, afb-daemon get an initial token. +This initial token must be presented by incoming client to be authenticated. A token is valid only for a period. -The token must be renewed periodically. When the token is renewed, afb-daemon -sends the new token to the client. +The token must be renewed periodically. +When the token is renewed, afb-daemon sends the new token to the client. Tokens generated by afb-daemon are UUIDs. @@ -78,21 +84,21 @@ Tokens generated by afb-daemon are UUIDs. It stand for Universal Unique IDentifier. It is designed to create identifier in a way that avoid has much as possible -conflicts. It means that if two different instances create an UUID, the +conflicts. +It means that if two different instances create an UUID, the probability that they create the same UUID is very low, near to zero. ## x-afb-reqid -Argument name that can be used with HTTP request. When this argument is given, -it is automatically added to the "request" object of the answer. +Argument name that can be used with HTTP request. +When this argument is given, it is automatically added to the "request" object of the answer. ## x-afb-token -Argument name meant to give the token without ambiguity. +Argument name meant to give the token without ambiguity. You can also use the name **token** but it may conflicts with others arguments. ## x-afb-uuid -Argument name for giving explicitly the session identifier without ambiguity. +Argument name for giving explicitly the session identifier without ambiguity. You can also use the name **uuid** but it may conflicts with others arguments. - diff --git a/docs/afb-desktop-package.md b/docs/afb-desktop-package.md index ad51c67d..832f41e6 100644 --- a/docs/afb-desktop-package.md +++ b/docs/afb-desktop-package.md @@ -1,14 +1,12 @@ - -Desktop packages for binder development -======================================== +# Desktop packages for binder development It exists packages of the ***binder*** (afb-daemon) for common desktop linux distributions. - - Fedora - - Ubuntu - - Debian - - Suse +- Fedora +- Ubuntu +- Debian +- Suse Installing the development package of the ***binder*** allows to write ***bindings*** that runs on the desktop @@ -16,25 +14,29 @@ computer of the developer. It is very convenient to quickly write and debug a binding. -Retrieving compiling option with pkg-config -========================================== +## Retrieving compiling option with pkg-config The ***binder*** afb-daemon provides a configuration -file for **pkg-config**. +file for **pkg-config**. Typing the command - pkg-config --cflags afb-daemon +```bash +pkg-config --cflags afb-daemon +``` Print flags use for compilation: - $ pkg-config --cflags afb-daemon - -I/opt/local/include -I/usr/include/json-c +```bash +$ pkg-config --cflags afb-daemon +-I/opt/local/include -I/usr/include/json-c +``` For linking, you should use - $ pkg-config --libs afb-daemon - -ljson-c +```bash +$ pkg-config --libs afb-daemon +-ljson-c +``` -It automatically includes the dependency to json-c. +It automatically includes the dependency to json-c. This is activated through **Requires** keyword in pkg-config. - diff --git a/docs/afb-events-guide.md b/docs/afb-events-guide.md index 2718003e..b4eedc61 100644 --- a/docs/afb-events-guide.md +++ b/docs/afb-events-guide.md @@ -1,15 +1,20 @@ -Guide for developing with events -================================ +# Guide for developing with events Signaling agents are services that send events to any clients that -subscribed for receiving it. The sent events carry any data. +subscribed for receiving it. +The sent events carry any data. -To have a good understanding of how to write a signaling agent, the -actions of subscribing, unsubscribing, producing, sending and receiving -events must be described and explained. +To have a good understanding of how to: -Overview of events ------------------- +- write a signaling agent. +- actions of subscribing. +- actions of unsubscribing. +- actions of producing. +- actions of sending and receiving. + +Events must be described and explained. + +## Overview of events The basis of a signaling agent is shown in the following figure: @@ -23,116 +28,139 @@ a “binding” are similar. ### Subscribing and unsubscribing -Subscribing is the action that makes a client able to receive data from a -signaling agent. Subscription must create resources for generating the data, and -for delivering the data to the client. These two aspects are not handled by the -same piece of software. Generating the data is the responsibility of the -developer of the signaling agent while delivering the data is handled by the -framework. +- Subscribing is the action that makes a client able to receive + data from a signaling agent. + +Subscription must : + +1. Create resources for generating the data. +1. Delivering the data to the client. + +These two aspects are not handled by the same piece of software. + +1. Generating the data is the responsibility of the developer of the signaling agent +1. Delivering the data is handled by the framework. When a client subscribes for data, the agent must: -1. check that the subscription request is correct; -2. establish the computation chain of the required data, if not already - done; -3. create a named event for the computed data, if not already done; -4. ask the framework to establish the subscription to the event for the - request; -5. 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. 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, this -is specific to the binding. +The first two steps are not involving 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, +this is specific to the binding. As said before, the framework uses and integrates **libsystemd** and its event -loop. Within the framework, **libsystemd** is the standard API/library for +loop. +Within the framework, **libsystemd** is the standard API/library for bindings expecting to setup and handle I/O, timer or signal events. Steps 3 and 4 are bound to the framework. The agent must create an object for handling the propagation of produced -data to its clients. That object is called “event” in the framework. An -event has a name that allows clients to distinguish it from other +data to its clients. +That object is called “event” in the framework. +An event has a name that allows clients to distinguish it from other events. Events are created using the ***afb\_daemon\_make\_event*** function -that takes the name of the event. Example: +that takes the name of the event. +Example: ```C - event = afb_daemon_make_event(name); + event = afb_daemon_make_event(name); ``` Once created, the event can be used either to push data to its subscribers or to broadcast data to any listener. The event must be used to establish the subscription for the requesting -client. This is done using the ***afb\_req\_subscribe*** function +client. +This is done using the ***afb\_req\_subscribe*** function that takes the current request object and event and associates them -together. Example: +together. +Example: ```C - rc = afb_req_subscribe(req, event); + rc = afb_req_subscribe(req, event); ``` When successful, this function make the connection between the event and -the client that emitted the request. The client becomes a subscriber of -the event until it unsubscribes or disconnects. The -***afb\_req\_subscribe*** function will fail if the client -connection is weak: if the request comes from a HTTP link. To receive -signals, the client must be connected. The AGL framework allows connections -using WebSocket. +the client that emitted the request. +The client becomes a subscriber of the event until it unsubscribes or disconnects. +The ***afb\_req\_subscribe*** function will fail: + +- if the client connection is weak. +- if the request comes from a HTTP link. + +To receive signals, the client must be connected. + +The AGL framework allows connections using WebSocket. The name of the event is either a well known name or an ad hoc name forged for the use case. -Let's see a basic example: client A expects to receive the speed in km/h -every second while client B expects the speed in mph twice a second. In -that case, there are two different events because it is not the same -unit and it is not the same frequency. Having two different events -allows to associate clients to the correct event. But this doesn't tell -any word about the name of these events. The designer of the signaling -agent has two options for naming: - -1. names can be the same (“speed” for example) with sent data - self describing itself or having a specific tag (requiring from - clients awareness about requesting both kinds of speed isn't safe). -2. names of the event include the variations (by example: - “speed-km/h-1Hz” and “speed-mph-2Hz”) and, in that case, sent data - can self describe itself or not. +Let's see a basic example: + +- client A expects to receive the speed in km/h every second. +- client B expects the speed in mph twice a second. + +In that case, there are two different events because it is not the same +unit and it is not the same frequency. +Having two different events allows to associate clients to the correct event. +But this doesn't tell any word about the name of these events. +The designer of the signaling agent has two options for naming: + +1. names can be the same (“speed” for example) with sent data + self describing itself or having a specific tag (requiring from + clients awareness about requesting both kinds of speed isn't safe). +1. names of the event include the variations (by example: + “speed-km/h-1Hz” and “speed-mph-2Hz”) and, in that case, sent data + can self describe itself or not. In both cases, the signaling agent might have to send the name of the event and/or an associated tag to its client in the reply of the -subscription. This is part of the step 5 above. +subscription. +This is part of the step 5 above. + +The framework only uses the event (not its name) for: -The framework only uses the event (not its name) for subscription, -un-subscription and pushing. +- subscription +- un-subscription +- pushing When the requested data is already generated and the event used for pushing it already exists, the signaling agent must not instantiate a new processing chain and must not create a new event object for pushing -data. The signaling agent must reuse the existing chain and event. +data. +The signaling agent must reuse the existing chain and event. -Unsubscribing is made by the signaling agent on a request of its client. +Unsubscribing is made by the signaling agent on a request of its client. The ***afb\_req\_unsubscribe*** function tells the framework to -remove the requesting client from the event's list of subscribers. +remove the requesting client from the event's list of subscribers. Example: ```C - afb_req_unsubscribe(req, event); + afb_req_unsubscribe(req, event); ``` -Subscription count does not matter to the framework: subscribing the -same client several times has the same effect that subscribing only one -time. Thus, when unsubscribing is invoked, it becomes immediately -effective. +Subscription count does not matter to the framework: + +- Subscribing the same client several times has the same effect that subscribing only one time. + +Thus, when unsubscribing is invoked, it becomes immediately effective. #### More on naming events -Within the AGL framework, a signaling agent is a binding that has an API -prefix. This prefix is meant to be unique and to identify the binding -API. The names of the events that this signaling agent creates are +- Within the AGL framework, a signaling agent is a binding that has an API prefix. + +This prefix is meant to be unique and to identify the binding API. +The names of the events that this signaling agent creates are automatically prefixed by the framework, using the API prefix of the binding. @@ -142,54 +170,58 @@ will receive an event of name ***api/event***. ### Generating and pushing signals and data -This of the responsibility of the designer of the signaling agent to -establish the processing chain for generating events. In many cases, -this can be achieved using I/O or timer or signal events inserted in the -main loop. For this case, the AGL framework uses **libsystemd** and +- This of the responsibility of the designer of the signaling agent to establish the processing chain for generating events. + +In many cases, this can be achieved using I/O or timer or signal events inserted in the main loop. +For this case, the AGL framework uses **libsystemd** and provide a way to integrates to the main loop of this library using -afb\_daemon\_get\_event\_loop. Example: +afb\_daemon\_get\_event\_loop. +Example: ```C - sdev = afb_daemon_get_event_loop(); - rc = sd_event_add_io(sdev, &source, fd, EPOLLIN, myfunction, NULL); + sdev = afb_daemon_get_event_loop(); + rc = sd_event_add_io(sdev, &source, fd, EPOLLIN, myfunction, NULL); ``` -In some other cases, the events are coming from D-Bus. In that case, the -framework also uses **libsystemd** internally to access D-Bus. It provides -two methods to get the available D-Bus objects, already existing and -bound to the main**libsystemd**event loop. Use either -***afb\_daemon\_get\_system\_bus*** or -***afb\_daemon\_get\_user\_bus*** to get the required instance. Then -use functions of **libsystemd** to handle D-Bus. +In some other cases, the events are coming from D-Bus. +In that case, the framework also uses **libsystemd** internally to access D-Bus. +It provides two methods to get the available D-Bus objects, already existing and +bound to the main **libsystemd** event loop. +Use either ***afb\_daemon\_get\_system\_bus*** or +***afb\_daemon\_get\_user\_bus*** to get the required instance. +Then use functions of **libsystemd** to handle D-Bus. In some rare cases, the generation of the data requires to start a new thread. When a data is generated and ready to be pushed, the signaling agent -should call the function ***afb\_event\_push***. Example: +should call the function ***afb\_event\_push***. +Example: ```C - rc = afb_event_push(event, JSON); - if (rc == 0) { - stop_generating(event); - afb_event_drop(event); - } + rc = afb_event_push(event, JSON); + if (rc == 0) { + stop_generating(event); + afb_event_drop(event); + } ``` -The function ***afb\_event\_push*** pushes json data to all the -subscribers. It then returns the count of subscribers. When the count is -zero, there is no subscriber listening for the event. The example above -shows that in that case, the signaling agent stops to generate data for -the event and delete the event using afb\_event\_drop. This is one -possible option. Other valuable options are: do nothing and continue to -generate and push the event or just stop to generate and push the data -but keep the event existing. +The function ***afb\_event\_push*** pushes json data to all the subscribers. +It then returns the count of subscribers. +When the count is zero, there is no subscriber listening for the event. +The example above shows that in that case, the signaling agent stops to generate data for the event and delete the event using afb\_event\_drop. +This is one possible option. +Other valuable options are: + +- do nothing and continue to generate and push the event. +- just stop to generate and push the data but keep the event existing. ### Receiving the signals Understanding what a client expects when it receives signals, events or data shall be the most important topic of the designer of a signaling -agent. The good point here is that because JSON[^1] is the exchange +agent. +The good point here is that because JSON[^1] is the exchange format, structured data can be sent in a flexible way. The good design is to allow as much as possible the client to describe @@ -199,38 +231,38 @@ requirements only. ### The exceptional case of wide broadcast Some data or events have so much importance that they can be widely -broadcasted to alert any listening client. Examples of such an alert -are: +broadcasted to alert any listening client. +Examples of such an alert are: -- system is entering/leaving “power safe” mode -- system is shutting down -- the car starts/stops moving -- ... +- system is entering/leaving “power safe” mode +- system is shutting down +- the car starts/stops moving +- ... An event can be broadcasted using one of the two following methods: -***afb\_daemon\_broadcast\_event*** or -***afb\_event\_broadcast***. + +- ***afb\_daemon\_broadcast\_event*** +- ***afb\_event\_broadcast*** Example 1: ```C - afb_daemon_broadcast_event(name, json); +afb_daemon_broadcast_event(name, json); ``` Example 2: ```C - event = afb_daemon_make_event(name); - . . . . - afb_event_broadcast(event, json); +event = afb_daemon_make_event(name); +. . . . +afb_event_broadcast(event, json); ``` As for other events, the name of events broadcasted using ***afb\_daemon\_broadcast\_event*** are automatically prefixed by the framework with API prefix of the binding (signaling agent). -Reference of functions ----------------------- +## Reference of functions ### Function afb\_event afb\_daemon\_make\_event @@ -312,8 +344,8 @@ below: int afb_req_unsubscribe(struct afb_req req, struct afb_event event); ``` -The un-subscription removes the client of the request of the list of subscribers -to the event. +The un-subscription removes the client of the request of the +list of subscribers to the event. When the list of subscribers to the event becomes empty, the function ***afb\_event\_push*** will return zero. @@ -338,7 +370,6 @@ int afb_event_broadcast(struct afb_event event, struct json_object *object); This uses an existing event (created with ***afb\_daemon\_make\_event***) for broadcasting an event having its name. - ### Function afb\_daemon\_broadcast\_event The function ***afb\_daemon\_broadcast\_event*** is defined as below: @@ -357,15 +388,17 @@ The function ***afb\_daemon\_broadcast\_event*** is defined as below: int afb_daemon_broadcast_event(const char *name, struct json_object *object); ``` -The name is given here explicitly. The name is automatically prefixed -with the name of the binding. For example, a binding of prefix "xxx" -would broadcast the event "xxx/name". +The name is given here explicitly. +The name is automatically prefixed with the name of the binding. +For example, a binding of prefix "xxx" would broadcast the event "xxx/name". ### Function onevent (field of afbBindingV2) Binding can designate an event handling function using the field **onevent** -of the structure **afbBindingV2**. This function is called when an event is -broadcasted or when an event the binding subscribed to is pushed. +of the structure **afbBindingV2**. +This function is called when an event is broadcasted or when an event the +binding subscribed to is pushed. That allow a service to react to an event and do what it is to do if this is -relevant for it (ie: car back camera detects imminent collision and broadcast -it, then appropriate service enable parking brake.). +relevant for it. +(ie: car back camera detects imminent collision and broadcast it, then +appropriate service enable parking brake.). diff --git a/docs/afb-migration-v1-to-v2.md b/docs/afb-migration-v1-to-v2.md index fd75ba56..f3182918 100644 --- a/docs/afb-migration-v1-to-v2.md +++ b/docs/afb-migration-v1-to-v2.md @@ -4,20 +4,21 @@ Migration from binding V1 to binding V2 The ***binding*** interface evolved from version 1 to version 2 for the following reasons: - - integration of the security requirements within the bindings - - simplification of the API (after developer feedbacks) - - removal of obscure features, cleanup +- integration of the security requirements within the bindings +- simplification of the API (after developer feedbacks) +- removal of obscure features, cleanup -The ***binder*** can run ***bindings*** v1 and/or v2 in any combination. -Thus moving from v1 to v2 is not enforced. There is no real need. +The ***binder*** can run ***bindings*** v1 and/or v2 in any combination. +Thus moving from v1 to v2 is not enforced, there is no real need. -More, it is possible to write a dual ***binding***: a ***binding*** that -implements the version 1 AND the version 2. +More, it is possible to write a dual ***binding***: + +- a ***binding*** that implements the version 1 and the version 2. However, IT IS HIGHLY RECOMMENDED TO SWITCH TO ONLY VERSION 2: - - any new development SHOULD start using ***binding*** V2 - - existing ***bindings*** SHOULD migrate to the version 2 +- any new development SHOULD start using ***binding*** V2 +- existing ***bindings*** SHOULD migrate to the version 2 This guide covers the migration of bindings from version 1 to version 2. @@ -25,30 +26,34 @@ It also explains some of the rationale taken when migrating from version 1 to ve In the future, if ***binding*** api evolves to fresh versions (3, 4, ...) it might be necessarily to write bindings implementing more than -just one version. For example, a ***binding*** being v2 AND v3 will resolve -the issue of running on older AND newer version of AGL. This should always -be possible even if more complicated. +just one version. +For example: + +- a ***binding*** being v2 AND v3 will resolve the issue of running on older and newer version of AGL. + +This should always be possible even if more complicated. Important things to known when migrating ---------------------------------------- One of the most important change when migrating from v1 to v2 is -that many functions use an hidden *common* variable. +that many functions use an hidden *common* variable. This affects the functions of the following classes: - - functions of class **daemon**: - * functions starting with **afb_daemon_...** - * functions for logging: **ERROR**, **WARNING**, **NOTICE**, **INFO**, **DEBUG** - - functions of class **service**: - * functions starting with **afb_service_...** - - callback functions: - * the register function (that is removed) - * the service init function - * the onevent function +- functions of class **daemon**: + - functions starting with **afb_daemon_...** + - functions for logging: **ERROR**, **WARNING**, **NOTICE**, **INFO**, **DEBUG** +- functions of class **service**: + - functions starting with **afb_service_...** +- callback functions: + - the register function (that is removed) + - the service init function + - the onevent function For these functions, the first parameter is now implicit. -Let takes an example. For ***binding*** v1 you had to write: +Let takes an example. +For ***binding*** v1 you had to write: ```C afb_daemon_broadcast_event(afbitf->daemon, reason, description); @@ -63,35 +68,36 @@ For ***binding*** v2, you simply write: This simplification is possible because the header files included for the bindings now provide a common variable for storing the **daemon** and **service** data. -As a programmer, you shouldn't care much about that hidden variable. +As a programmer, you shouldn't care much about that hidden variable. It simplifies the job, that's all and that is the reason of the change. An other important difference is between the version 1 and the version 2 is -on how the ***binding***'s **API** is documented. The version 2 emphasis the -**OpenAPI v3** description of the **API**. For this reason, to avoid -duplication of descriptions, only one description is expected: the **OpenAPI** one. +on how the ***binding***'s **API** is documented. +The version 2 emphasis the **OpenAPI v3** description of the **API**. +For this reason, to avoid duplication of descriptions, only one description is expected: + +- The **OpenAPI** one. Task list for the migration --------------------------- This task list is: - 1. Enforce use of binding v2 by setting **AFB_BINDING_VERSION** - 2. Rewrite the main structure and the list of exported verbs - 3. Adapt the init and callback functions - 4. Removes the first parameter of functions of classes **daemon** - and **service** - 5. Consider where to emit logs for requests - 6. Take care of store/unstore changes - 7. Consider use of synchronous (sub)call requests - 8. Optionally, removes explicit struct +1. Enforce use of binding v2 by setting **AFB_BINDING_VERSION** +1. Rewrite the main structure and the list of exported verbs +1. Adapt the init and callback functions +1. Removes the first parameter of functions of classes **daemon** and **service** +1. Consider where to emit logs for requests +1. Take care of store/unstore changes +1. Consider use of synchronous (sub)call requests +1. Optionally, removes explicit struct The remaining chapters explain these task with more details. Enforce use of binding v2 by setting AFB_BINDING_VERSION -------------------------------------------------------- -By defining **AFB_BINDING_VERSION** to **2** you switch to version 2. +By defining **AFB_BINDING_VERSION** to **2** you switch to version 2. This is done as below. ```C @@ -107,7 +113,9 @@ Rewrite the main structures and the list of exported verbs The structures describing the ***binding** changed from version 1 to version 2. The structure for describing verbs changed to include security -requirements. In version 1 it was: +requirements. + +In version 1 it was: ```C struct afb_verb_desc_v1 @@ -126,7 +134,7 @@ struct afb_verb_v2 { const char *verb; /* name of the verb */ void (*callback)(struct afb_req req); /* callback function implementing the verb */ - const struct afb_auth *auth; /* required authorization */ + const struct afb_auth *auth; /* required authorization */ uint32_t session; /* authorization and session requirements of the verb */ }; @@ -134,10 +142,10 @@ struct afb_verb_v2 The migration of instances of that structure requires the following actions: - - rename field **name** to **verb** - - remove field **info** - - adapt field **session** if needed - - set field **auth** to NULL +- rename field **name** to **verb** +- remove field **info** +- adapt field **session** if needed +- set field **auth** to NULL Example: @@ -154,7 +162,9 @@ Becomes The field **auth** can be set to a value describing the requested authorization. -The main describing structure also changed. In version 1 it was: +The main describing structure also changed. + +In version 1 it was: ```C struct afb_binding_desc_v1 @@ -170,25 +180,25 @@ In version 2 it becomes: ```C struct afb_binding_v2 { - const char *api; /* api name for the binding */ - const char *specification; /* textual specification of the binding */ - const struct afb_verb_v2 *verbs; /* array of descriptions of verbs terminated by a NULL name */ + const char *api; /* api name for the binding */ + const char *specification; /* textual specification of the binding */ + const struct afb_verb_v2 *verbs; /* array of descriptions of verbs terminated by a NULL name */ int (*preinit)(); /* callback at load of the binding */ int (*init)(); /* callback for starting the service */ void (*onevent)(const char *event, struct json_object *object); /* callback for handling events */ - unsigned noconcurrency: 1; /* avoids concurrent requests to verbs */ + unsigned noconcurrency: 1; /* avoids concurrent requests to verbs */ }; ``` The migration of instances of that structure requires the following actions: - - declare, explore, name the structure as ```const struct afb_binding_v2 afbBindingV2``` - - rename the field **prefix** to **api** - - remove the field **info** - - setup the fields **preinit**, **init**, **onevent** according to the next section - - set the field **noconcurrency** to the right value: - * to 1 if you want to avoid concurrent calls to verbs. - * to 0 if you allow concurrent calls to verbs. +- declare, explore, name the structure as ```const struct afb_binding_v2 afbBindingV2``` +- rename the field **prefix** to **api** +- remove the field **info** +- setup the fields **preinit**, **init**, **onevent** according to the next section +- set the field **noconcurrency** to the right value: + - to 1 if you want to avoid concurrent calls to verbs. + - to 0 if you allow concurrent calls to verbs. Example: @@ -201,6 +211,7 @@ static const struct afb_binding plugin_desc = { .verbs = verbs } ``` + Becomes: ```C @@ -214,37 +225,38 @@ const struct afb_binding_v2 afbBindingV2 = { ``` The **binder** now relies only on the exported names -to deduce the type of the binding. This make the main -structure more simple. +to deduce the type of the binding. +This make the main structure more simple. Adapt the init and callback functions ------------------------------------- The ***bindings*** version 1 defined 3 exported functions: - - **afbBindingV1Register** - - **afbBindingV1ServiceInit** - - **afbBindingV1ServiceEvent** +- **afbBindingV1Register** +- **afbBindingV1ServiceInit** +- **afbBindingV1ServiceEvent** These function should not be exported any more and there definition changed. -The function **afbBindingV1Register** is no more used to describe the binding. +The function **afbBindingV1Register** is no more used to describe the binding. When a binding has to take actions when it is loaded, it must set the field -**preinit** of the structure **afbBindingV2**. This field, this preinit, might -be used to check features at load. When it returns a negative number, the -***binder*** stops before initializing any ***binding***. +**preinit** of the structure **afbBindingV2**. +This field, this preinit, might be used to check features at load. +When it returns a negative number, the ***binder*** stops before initializing any ***binding***. The function **afbBindingV1ServiceInit** is replaced by the field **init** -of the structure **afbBindingV2**. The init function should return 0 in case -of success or a negative error code in case of problem. It is called during -initialization of services. +of the structure **afbBindingV2**. +The init function should return 0 in case of success or a negative error code +in case of problem. +It is called during initialization of services. The function **afbBindingV1ServiceEvent**is replaced by the field **onevent** of the structure **afbBindingV2**. The two functions **afbBindingV1Register** and **afbBindingV1ServiceInit**, -were taking as parameter the ***binder*** interface and the service interface respectively. -These interfaces are now managed hiddenly for the **binding** by the **binder**. +were taking as parameter the ***binder*** interface and the service interface respectively. +These interfaces are now managed hiddenly for the **binding** by the **binder**. So the variable that ***bindings*** version used to store the ***binder*** interface and the service interface are no more needed and can be removed. @@ -314,12 +326,13 @@ const struct afb_binding_v2 afbBindingV2 = { ``` The two functions **afbBindingV1Register** and **afbBindingV1ServiceInit**, -were taking as parameter the ***binder*** interface and the service interface respectively. -These interfaces are now managed hiddenly for the **binding** by the **binder**. +were taking as parameter the ***binder*** interface and the service interface respectively. +These interfaces are now managed hiddenly for the **binding** by the **binder**. So the variable that ***bindings*** version used to store the ***binder*** interface and the service interface are no more needed and can be removed. On the above example the following lines were removed: + ```C const struct afb_binding_interface *interface; struct afb_service service; @@ -329,23 +342,21 @@ struct afb_service service; service = svc; ``` - - Removes the first parameter of functions of classes **daemon** and **service** ------------------------------------------------------------------------------ As explained before, many functions loose there first arguments, this are the functions of the following classes: - - functions of class **daemon**: - * functions starting with **afb_daemon_...** - * functions for logging: **ERROR**, **WARNING**, **NOTICE**, **INFO**, **DEBUG** - - functions of class **service**: - * functions starting with **afb_service_...** - - callback functions: - * the register function (that is removed) - * the service init function - * the onevent function +- functions of class **daemon**: + - functions starting with **afb_daemon_...** + - functions for logging: **ERROR**, **WARNING**, **NOTICE**, **INFO**, **DEBUG** +- functions of class **service**: + - functions starting with **afb_service_...** +- callback functions: + - the register function (that is removed) + - the service init function + - the onevent function For these functions, the first parameter is now implicit. @@ -361,10 +372,24 @@ Becomes: afb_daemon_broadcast_event(reason, description); ``` -Also, to avoid possible conflicts, we introduced prefixed logging functions: -the macros **ERROR**, **WARNING**, **NOTICE**, **INFO**, **DEBUG** have now -a prefixed version: **AFB\_ERROR**, **AFB\_WARNING**, **AFB\_NOTICE**, -**AFB\_INFO**, **AFB\_DEBUG**. It is now recommended to use the prefixed version. +Also, to avoid possible conflicts, we introduced prefixed logging functions: +the macros + +- **ERROR** +- **WARNING** +- **NOTICE** +- **INFO** +- **DEBUG** + +have now a prefixed version: + +- **AFB\_ERROR** +- **AFB\_WARNING** +- **AFB\_NOTICE** +- **AFB\_INFO** +- **AFB\_DEBUG** + +It is now recommended to use the prefixed version. Example: @@ -384,8 +409,18 @@ or, better: AFB_NOTICE("hello plugin comes to live"); ``` -To remove definition of the un-prefixed versions of logging macros **ERROR**, **WARNING**, -**NOTICE**, **INFO**, **DEBUG** and just define **AFB_BINDING_PRAGMA_NO_VERBOSE_UNPREFIX** +To remove definition of the un-prefixed versions of logging macros: + +- **ERROR** +- **WARNING** +- **NOTICE** +- **INFO** +- **DEBUG** + +and just define + +- **AFB_BINDING_PRAGMA_NO_VERBOSE_UNPREFIX** + before to include **afb/afb-binding.h**. ```C @@ -397,12 +432,17 @@ before to include **afb/afb-binding.h**. Consider where to emit logs for requests ---------------------------------------- -The ***bindings*** v2 now allows to emit log messages associated to ***requests***. +The ***bindings*** v2 now allows to emit log messages associated to ***requests***. This feature is valuable when debugging because it allows to return side information associated to a ***request***. -The defined macros for logging to requests are: **AFB_REQ_ERROR**, -**AFB_REQ_WARNING**, **AFB_REQ_NOTICE**, **AFB_REQ_INFO**, **AFB_REQ_DEBUG**. +The defined macros for logging to requests are: + +- **AFB_REQ_ERROR** +- **AFB_REQ_WARNING** +- **AFB_REQ_NOTICE** +- **AFB_REQ_INFO** +- **AFB_REQ_DEBUG** We encourage the use of these new logging facilities everywhere it makes sense. @@ -422,8 +462,8 @@ Take care of store/unstore change --------------------------------- For efficiency, the version 2 redefined how storing/un-storing of -requests works. Storing request is needed for asynchronous handling -of requests. +requests works. +Storing request is needed for asynchronous handling of requests. For ***bindings*** version, the signature of the functions were: @@ -451,8 +491,8 @@ Consider use of synchronous (sub)call requests ---------------------------------------------- ***Bindings*** can emit requests for themselves (calls) or for -their clients (subcalls). With ***bindings*** version 2 comes -also synchronous requests for both cases. +their clients (subcalls). +With ***bindings*** version 2 comes also synchronous requests for both cases. So when migrating to bindings version 2, a developer can consider to replace the asynchronous requests (with asynchronous call back) @@ -497,9 +537,8 @@ static void verb(afb_req req) Example of migration -------------------- -The first ***binding*** that migrated from v1 to v2 was -the sample **HelloWorld**. Here is shown the differences between -the version 1 and the version 2. +The first ***binding*** that migrated from v1 to v2 was the sample **HelloWorld**. +Here is shown the differences between the version 1 and the version 2. ```diff diff --git a/bindings/samples/HelloWorld.c b/bindings/samples/HelloWorld.c @@ -521,8 +560,8 @@ index c6fa779..505aee3 100644 strcpy(e->tag, tag); /* make the event */ -- e->event = afb_daemon_make_event(interface->daemon, name); -+ e->event = afb_daemon_make_event(name); +- e->event = afb_daemon_make_event(interface->daemon, name); ++ e->event = afb_daemon_make_event(name); if (!e->event.closure) { free(e); return -1; } /* link */ @@ -530,8 +569,8 @@ index c6fa779..505aee3 100644 static void pingEvent(struct afb_req request) { json_object *query = afb_req_json(request); -- afb_daemon_broadcast_event(interface->daemon, "event", json_object_get(query)); -+ afb_daemon_broadcast_event("event", json_object_get(query)); +- afb_daemon_broadcast_event(interface->daemon, "event", json_object_get(query)); ++ afb_daemon_broadcast_event("event", json_object_get(query)); ping(request, json_object_get(query), "event"); } @@ -541,14 +580,14 @@ index c6fa779..505aee3 100644 +static int preinit() +{ -+ AFB_NOTICE("hello binding comes to live"); -+ return 0; ++ AFB_NOTICE("hello binding comes to live"); ++ return 0; +} + +static int init() +{ -+ AFB_NOTICE("hello binding starting"); -+ return 0; ++ AFB_NOTICE("hello binding starting"); ++ return 0; +} + // NOTE: this sample does not use session to keep test a basic as possible @@ -588,24 +627,24 @@ index c6fa779..505aee3 100644 }; -static const struct afb_binding plugin_desc = { -- .type = AFB_BINDING_VERSION_1, -- .v1 = { -- .info = "Minimal Hello World Sample", -- .prefix = "hello", -- .verbs = verbs -- } +- .type = AFB_BINDING_VERSION_1, +- .v1 = { +- .info = "Minimal Hello World Sample", +- .prefix = "hello", +- .verbs = verbs +- } +const struct afb_binding_v2 afbBindingV2 = { -+ .api = "hello", -+ .specification = NULL, -+ .verbs = verbs, -+ .preinit = preinit, -+ .init = init ++ .api = "hello", ++ .specification = NULL, ++ .verbs = verbs, ++ .preinit = preinit, ++ .init = init }; -const struct afb_binding *afbBindingV1Register (const struct afb_binding_interface *itf) -{ -- interface = itf; -- NOTICE(interface, "hello plugin comes to live"); -- return &plugin_desc; +- interface = itf; +- NOTICE(interface, "hello plugin comes to live"); +- return &plugin_desc; -} ```
\ No newline at end of file diff --git a/docs/afb-overview.md b/docs/afb-overview.md index d0615ed5..0cff24cc 100644 --- a/docs/afb-overview.md +++ b/docs/afb-overview.md @@ -1,32 +1,26 @@ - -Binder Overview -=============== +# Binder Overview The ***binder*** provides the way to connect applications to -the services that it needs. It provides a fast way -to securely offer APIs to applications written in -any language and running almost anywhere. +the services that it needs. -The ***binder*** is developed for AGL. +It provides a fast way to securely offer APIs to applications +written in any language and running almost anywhere. -The ***binder*** is the usual name. -The binary is named **afb-daemon**. +- The ***binder*** is developed for AGL. +- The ***binder*** is the usual name. +- The binary is named **afb-daemon**. +- The name **afb-daemon** stands for ***Application Framework Binder Daemon***. -The name **afb-daemon** stands for ***Application -Framework Binder Daemon***. The word *daemon*, here, -denote the fact that the ***binder*** makes witchcraft to -connect applications to their expected services (note that usually -the term of daemon denotes background process but not here). +The word *daemon*, here, denote the fact that the ***binder*** makes witchcraft to +connect applications to their expected services. +(note: that usually the term of daemon denotes background process but not here). -Each ***binder*** **afb-daemon** is in charge to bind -one instance of an application or service to the rest -of the system, applications and services. -Within AGL, the connection between services and/or -applications is tuned by the AGL framework and -the AGL system. +Each ***binder*** **afb-daemon** is in charge to bind one instance of +an application or service to the rest of the system, applications and services. +Within AGL, the connection between services and/or applications +is tuned by the AGL framework and the AGL system. -The basis of the binder -======================= +## The basis of the binder The following figure shows main concepts linked to the ***binder***. @@ -35,24 +29,24 @@ The following figure shows main concepts linked to the ***binder***. The shown elements are: -* The SECURITY CONTEXT +- The SECURITY CONTEXT The primary intend of any ***binder*** is to provide - a secured environment for any application. On AGL, the - **security context** is ensured by [Smack][Smack] a security context, - the security context of the application or service. + a secured environment for any application. + On AGL, the **security context** is ensured by [Smack] + , the security context of the application or service. -* The BINDER +- The BINDER - This is the central element. It makes possible to run HTML5 - applications and provides the unified access to APIs provided - by the ***bindings***. + This is the central element. + It makes possible to run HTML5 applications and provides + the unified access to APIs provided by the ***bindings***. - Running a pure HTML5 application doesn't require any ***binding***. - in that case , the ***binder*** acts as a simple HTTP server for + Running a pure HTML5 application doesn't require any ***binding***. + In that case , the ***binder*** acts as a simple HTTP server for the web runtime. -* The BINDINGs +- The BINDINGs A ***binding*** adds one **API** to the ***binder***. @@ -61,16 +55,15 @@ The shown elements are: ***bindings*** are either: - - dynamically loaded libraries in the ***binder*** process - - remote service running on the same host - - remote service running on other hosts + - dynamically loaded libraries in the ***binder*** process + - remote service running on the same host + - remote service running on other hosts When acting as an HTTP server, the binder treats the language settings of the HTTP requests to provide internationalized content as specified by [widget specifications](https://www.w3.org/TR/widgets/#internationalization-and-localization). - -* The APPLICATION +- The APPLICATION An ***application*** connects to the binder to get access to the **API** that it provides or to get its HTTP services to access @@ -78,8 +71,7 @@ The shown elements are: <!-- pagebreak --> -Interconnection of binders -========================== +## Interconnection of binders The AGL framework interprets the **widget/application** manifests to setup the ***bindings*** configuration of the ***binders***. diff --git a/docs/annexes.md b/docs/annexes.md index ea4a0dcf..2304bfb0 100644 --- a/docs/annexes.md +++ b/docs/annexes.md @@ -1,5 +1,4 @@ -Annexes -======= +# Annexes - * [Installing the binder on a desktop](afb-desktop-package.md) - * [Options of afb-daemon](afb-daemon-options.md)
\ No newline at end of file +* [Installing the binder on a desktop](afb-desktop-package.md) +* [Options of afb-daemon](afb-daemon-options.md)
\ No newline at end of file |