From 8160b5cdc8547277f3f31ee1e41524754d5d987d Mon Sep 17 00:00:00 2001 From: Jan-Simon Möller Date: Wed, 26 Jan 2022 12:25:31 +0100 Subject: Update to documentation before Marlin MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is mostly a cleanup before the Magic Marlin Release. We do have the Application Framework chapter rewrite pending. Bug-AGL: SPEC-4236 Signed-off-by: Jan-Simon Möller Change-Id: I7e1f39667b4db417497b1d0c84065c173fa18439 Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/27097 --- .../2_Application_Framework_Binder/0_Overview.md | 91 - .../1_Binder_daemon_vocabulary.md | 104 - .../2_How_to_write_a_binding.md | 444 ---- .../3_Binder_References.md | 2524 -------------------- .../4_Binder_events_guide.md | 291 --- .../5_Binder_Application_writing_guide.md | 319 --- .../7_Document_revisions.md | 17 - .../Annexes/1_Migration_to_bindings_v3.md | 199 -- .../Annexes/2_WebSocket_protocol_x-afb-ws-json1.md | 308 --- .../3_Installing_the_binder_on_a_desktop.md | 44 - .../Annexes/4_Options_of_afb-daemon.md | 355 --- .../Annexes/5_Debugging_binder_and_bindings.md | 38 - .../Annexes/6_LEGACY_Migration_from_v1_to_v2.md | 656 ----- .../Annexes/7_LEGACY_Binding_v2_references.md | 757 ------ .../images/basis.svg | 356 --- .../images/interconnection.svg | 854 ------- .../images/signaling-basis.svg | 145 -- 17 files changed, 7502 deletions(-) delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/0_Overview.md delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/1_Binder_daemon_vocabulary.md delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/2_How_to_write_a_binding.md delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/3_Binder_References.md delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/4_Binder_events_guide.md delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/5_Binder_Application_writing_guide.md delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/7_Document_revisions.md delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/1_Migration_to_bindings_v3.md delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/2_WebSocket_protocol_x-afb-ws-json1.md delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/3_Installing_the_binder_on_a_desktop.md delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/4_Options_of_afb-daemon.md delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/5_Debugging_binder_and_bindings.md delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/6_LEGACY_Migration_from_v1_to_v2.md delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/7_LEGACY_Binding_v2_references.md delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/images/basis.svg delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/images/interconnection.svg delete mode 100644 docs/3_Developer_Guides/2_Application_Framework_Binder/images/signaling-basis.svg (limited to 'docs/3_Developer_Guides/2_Application_Framework_Binder') diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/0_Overview.md b/docs/3_Developer_Guides/2_Application_Framework_Binder/0_Overview.md deleted file mode 100644 index 22a88ba..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/0_Overview.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: 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 ***binder*** is developed for AGL (Automotive Grade Linux) but it is not bound to AGL. -- The ***binder*** is the usual name. -- The binary is named **afb-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). - -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 following figure shows main concepts linked to the ***binder***. - -![Figure: binder basis](images/basis.svg) - -The shown elements are: - -- The SECURITY CONTEXT - - 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. - -- 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***. - - 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 - - A ***binding*** adds one **API** to the ***binder***. - - An **API** is a set of **verbs** that can be called - using either REST over HTTP or a kind of JSON RPC. - - ***bindings*** are either: - - - 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 - - An ***application*** connects to the binder to get access to - the **API** that it provides or to get its HTTP services to access - resources. - -## Interconnection of binders - -The AGL framework interprets the **widget/application** manifests -to setup the ***bindings*** configuration of the ***binders***. - -The figure below shows that ***binders*** are interconnected. - -![Figure: binder interconnection](images/interconnection.svg) - -The figure shows 4 several **application/service**: **A**, **B**, -**C** and **D**. - -The application **A** might use an **API** that is shown as a -local ***binding*** but that in reality runs within the context -of **D**. - -The framework AGL takes care of making the plumbing working. \ No newline at end of file diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/1_Binder_daemon_vocabulary.md b/docs/3_Developer_Guides/2_Application_Framework_Binder/1_Binder_daemon_vocabulary.md deleted file mode 100644 index 9839e65..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/1_Binder_daemon_vocabulary.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Binder daemon vocabulary ---- - -## Binding - -A shared library object intended to add a functionality to an afb-daemon -instance. -It implements an API and may provide a service. - -Binding made for services can have specific entry points called after -initialization and before serving. - -## Event - -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. - -## Level of assurance (LOA) - -This level that can be from 0 to 3 represent the level of -assurance that the services can expect from the session. - -The exact definition of the meaning of these levels and how to use it remains to -be achieved. - -## Request - -A request is an invocation by a client to a binding method using a message -transferred through some protocol: - -- HTTP -- WebSocket -- ... - -and served by ***afb-daemon*** - -## Reply/Response - -This is a message sent to client as the result of the request. - -## Service - -Service are made of bindings running on a binder -The binder is in charge of connecting services and applications. -A service can serve many clients. - -The framework establishes connection between the services and the clients. -Using sockets currently but other protocols are considered. - -The term of service is tightly bound to the notion of API. - -## 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. -A client can present its own session id. - -Internally, afb-daemon offers a mechanism to attach data to sessions. -When a session is closed or disappears, data attached to that session -are freed. - -## Token - -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. - -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. - -Tokens generated by afb-daemon are UUIDs. - -## UUID - -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 -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. - -## x-afb-token - -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. -You can also use the name **uuid** but it may conflicts with others arguments. diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/2_How_to_write_a_binding.md b/docs/3_Developer_Guides/2_Application_Framework_Binder/2_How_to_write_a_binding.md deleted file mode 100644 index d739167..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/2_How_to_write_a_binding.md +++ /dev/null @@ -1,444 +0,0 @@ ---- -title: How to write a binding? ---- - -# Overview of the bindings - -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. - -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 for 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***. -It is intended to provide one **API** (**A**pplication **P**rogramming -**I**nterface). - -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 -processes requests of applications and sends results. - -The ***binding***'s methods are invoked by HTTP or websocket -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**. -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 { ' ', '"', '#', '%', '&', - '\'', '/', '?', '`', '\x7f' } - -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**. - -## Versions of the bindings - -Since introduction of the binder, the way how bindings are written -evolved a little. While changing, attention was made to ensure binary -compatibility between the different versions. - -Actually it exists 3 ways of writing ***bindings***. -You can either write: - -- a binding version 1 (not more supported); -- a binding version 2 (not recommended); -- a binding version 3 (RECOMMENDED). - -A ***binder*** loads and runs any of these version in any combination. -This document explain how to write bindings version 3. - -## Sample binding: tuto-1 - -This is the code of the binding **tuto-1.c**: - -```C - 1 #define AFB_BINDING_VERSION 3 - 2 #include - 3 - 4 void hello(afb_req_t req) - 5 { - 6 AFB_REQ_DEBUG(req, "hello world"); - 7 afb_req_reply(req, NULL, NULL, "hello world"); - 8 } - 9 - 10 const afb_verb_t verbs[] = { - 11 { .verb="hello", .callback=hello }, - 12 { .verb=NULL } - 13 }; - 14 - 15 const afb_binding_t afbBindingExport = { - 16 .api = "tuto-1", - 17 .verbs = verbs - 18 }; -``` - -Compiling: - -```bash -gcc -fPIC -shared tuto-1.c -o tuto-1.so $(pkg-config --cflags-only-I afb-daemon) -``` - -> Note: the variable environment variable PKG_CONFIG_PATH might be necessary -> tuned to get **pkg-config** working properly - -Running: - -```bash -afb-daemon --binding ./tuto-1.so --port 3333 --token '' -``` - -At this point, afb-daemon has started, it loaded the binding tuto-1.so and now -listen at localhost on the port 3333. - -Testing using **curl**: - -```bash -$ curl http://localhost:3333/api/tuto-1/hello -{"jtype":"afb-reply","request":{"status":"success","info":"hello world","uuid":"1e587b54-900b-49ab-9940-46141bc2e1d6"}} -``` - -Testing using **afb-client-demo** (with option -H for -getting a human readable output): - -```bash -$ afb-client-demo -H ws://localhost:3333/api?token=x tuto-1 hello -ON-REPLY 1:tuto-1/hello: OK -{ - "jtype":"afb-reply", - "request":{ - "status":"success", - "info":"hello world", - "uuid":"03a84ad1-458a-4ace-af74-b1da917391b9" - } -} -``` - -This shows basic things: - -- The include to get for creating a binding -- How to declare the API offered by the binding -- How to handle requests made to the binding - -### Getting declarations for the binding - -The lines 1 and 2 show how to get the include file **afb-binding.h**. - -```C - 1 #define AFB_BINDING_VERSION 3 - 2 #include -``` - -You must define the version of ***binding*** that you are using. -This is done line 1 where we define that this is the version 3 (earlier -versions 1 and 2 are deprecated). - -If you don't define it, an error is reported and the compilation aborts. - -To include **afb-binding.h** successfully, the include search path -should be set correctly if needed (not needed only if installed in -/usr/include/afb directory that is the default). - -Setting the include path is easy using **pkg-config**: - -```bash -pkg-config --cflags-only-I afb-daemon -``` - -> Note for **C++** developers: -> -> The ***binder*** currently expose a draft version of **C++** api. -> To get it include the file <**afb/afb-binding**> (without **.h**). - - -### Declaring the API of the binding - -Lines 10 to 18 show the declaration of the ***binding***. - -The ***binder*** knows that this is a ***binding*** because -it finds the exported symbol **afbBindingExport** that is expected to be -a structure of type **afb_binding_t**. - -```C - 10 const afb_verb_t verbs[] = { - 11 { .verb="hello", .callback=hello }, - 12 { .verb=NULL } - 13 }; - 14 - 15 const afb_binding_t afbBindingExport = { - 16 .api = "tuto-1", - 17 .verbs = verbs - 18 }; -``` - -The structure **afbBindingExport** actually tells that: - -- 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 of -type **afb_verb_t**, each describing a verb, ended with a verb NULL (line 12). - -The only defined verb here (line 11) is named **hello** (field **.verb**) -and the function that handle the related request is **hello** -(field **.callback**). - -### Handling binder's requests - -As shown above this is by default the common include directory where -the AGL stuff is installed. - -```C - 4 void hello(afb_req_t req) - 5 { - 6 AFB_REQ_DEBUG(req, "hello world"); - 7 afb_req_reply(req, NULL, NULL, "hello world"); - 8 } -``` - -When the ***binder*** receives a request for the verb **hello** of -of the api **tuto-1**, it invoke the callback **hello** of the **binding** -with the argument **req** that handles the client request. - -The callback has to treat synchronously or asynchronously the request and -should at the end emit a reply for the request. - -At the line 7, the callback for **tuto-1/hello** replies to the request **req**. -Parameters of the reply are: - - 1. The first parameter is the replied request - 2. The second parameter is a json object (here NULL) - 3. The third parameter is the error string indication (here NULL: no error) - 4. The fourth parameter is an informative string (that can be NULL) that can be used to provide meta data. - -The 3 last parameters are sent back to the client as the reply content. - - - -## 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. - -This is the code of the binding **tuto-2.c**: - -```C - 1 #include - 2 #include - 3 - 4 #define AFB_BINDING_VERSION 3 - 5 #include - 6 - 7 afb_event_t event_login, event_logout; - 8 - 9 void login(afb_req_t req) - 10 { - 11 json_object *args, *user, *passwd; - 12 char *usr; - 13 - 14 args = afb_req_json(req); - 15 if (!json_object_object_get_ex(args, "user", &user) - 16 || !json_object_object_get_ex(args, "password", &passwd)) { - 17 AFB_REQ_ERROR(req, "login, bad request: %s", json_object_get_string(args)); - 18 afb_req_reply(req, NULL, "bad-request", NULL); - 19 } else if (afb_req_context_get(req)) { - 20 AFB_REQ_ERROR(req, "login, bad state, logout first"); - 21 afb_req_reply(req, NULL, "bad-state", NULL); - 22 } else if (strcmp(json_object_get_string(passwd), "please")) { - 23 AFB_REQ_ERROR(req, "login, unauthorized: %s", json_object_get_string(args)); - 24 afb_req_reply(req, NULL, "unauthorized", NULL); - 25 } else { - 26 usr = strdup(json_object_get_string(user)); - 27 AFB_REQ_NOTICE(req, "login user: %s", usr); - 28 afb_req_session_set_LOA(req, 1); - 29 afb_req_context_set(req, usr, free); - 30 afb_req_reply(req, NULL, NULL, NULL); - 31 afb_event_push(event_login, json_object_new_string(usr)); - 32 } - 33 } - 34 - 35 void action(afb_req_t req) - 36 { - 37 json_object *args, *val; - 38 char *usr; - 39 - 40 args = afb_req_json(req); - 41 usr = afb_req_context_get(req); - 42 AFB_REQ_NOTICE(req, "action for user %s: %s", usr, json_object_get_string(args)); - 43 if (json_object_object_get_ex(args, "subscribe", &val)) { - 44 if (json_object_get_boolean(val)) { - 45 AFB_REQ_NOTICE(req, "user %s subscribes to events", usr); - 46 afb_req_subscribe(req, event_login); - 47 afb_req_subscribe(req, event_logout); - 48 } else { - 49 AFB_REQ_NOTICE(req, "user %s unsubscribes to events", usr); - 50 afb_req_unsubscribe(req, event_login); - 51 afb_req_unsubscribe(req, event_logout); - 52 } - 53 } - 54 afb_req_reply(req, json_object_get(args), NULL, NULL); - 55 } - 56 - 57 void logout(afb_req_t req) - 58 { - 59 char *usr; - 60 - 61 usr = afb_req_context_get(req); - 62 AFB_REQ_NOTICE(req, "login user %s out", usr); - 63 afb_event_push(event_logout, json_object_new_string(usr)); - 64 afb_req_session_set_LOA(req, 0); - 65 afb_req_context_clear(req); - 66 afb_req_reply(req, NULL, NULL, NULL); - 67 } - 68 - 69 int preinit(afb_api_t api) - 70 { - 71 AFB_API_NOTICE(api, "preinit"); - 72 return 0; - 73 } - 74 - 75 int init(afb_api_t api) - 76 { - 77 AFB_API_NOTICE(api, "init"); - 78 event_login = afb_api_make_event(api, "login"); - 79 event_logout = afb_api_make_event(api, "logout"); - 80 if (afb_event_is_valid(event_login) && afb_event_is_valid(event_logout)) - 81 return 0; - 82 AFB_API_ERROR(api, "Can't create events"); - 83 return -1; - 84 } - 85 - 86 const afb_verb_t verbs[] = { - 87 { .verb="login", .callback=login }, - 88 { .verb="action", .callback=action, .session=AFB_SESSION_LOA_1 }, - 89 { .verb="logout", .callback=logout, .session=AFB_SESSION_LOA_1 }, - 90 { .verb=NULL } - 91 }; - 92 - 93 const afb_binding_t afbBindingExport = { - 94 .api = "tuto-2", - 95 .specification = NULL, - 96 .verbs = verbs, - 97 .preinit = preinit, - 98 .init = init, - 99 .noconcurrency = 0 - 100 }; -``` - -Compiling: - -```bash -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 '' -``` - -Testing: - -```bash -$ afb-client-demo -H localhost:3333/api?token=toto -tuto-2 login {"help":true} -ON-REPLY 1:tuto-2/login: ERROR -{ - "jtype":"afb-reply", - "request":{ - "status":"bad-request", - "uuid":"e2b24a13-fc43-487e-a5f4-9266dd1e60a9" - } -} -tuto-2 login {"user":"jose","password":"please"} -ON-REPLY 2:tuto-2/login: OK -{ - "jtype":"afb-reply", - "request":{ - "status":"success" - } -} -tuto-2 login {"user":"jobol","password":"please"} -ON-REPLY 3:tuto-2/login: ERROR -{ - "jtype":"afb-reply", - "request":{ - "status":"bad-state" - } -} -tuto-2 action {"subscribe":true} -ON-REPLY 4:tuto-2/action: OK -{ - "response":{ - "subscribe":true - }, - "jtype":"afb-reply", - "request":{ - "status":"success" - } -} -``` - -In another terminal: - -```bash -$ afb-client-demo -H localhost:3333/api?token=toto -tuto-2 login {"user":"jobol","password":"please"} -ON-REPLY 1:tuto-2/login: OK -{ - "jtype":"afb-reply", - "request":{ - "status":"success", - "uuid":"a09f55ff-0e89-4f4e-8415-c6e0e7f439be" - } -} -tuto-2 logout true -ON-REPLY 2:tuto-2/logout: OK -{ - "jtype":"afb-reply", - "request":{ - "status":"success" - } -} -``` - -It produced in the first terminal: - -```bash -ON-EVENT tuto-2/login: -{ - "event":"tuto-2\/login", - "data":"jobol", - "jtype":"afb-event" -} -ON-EVENT tuto-2/logout: -{ - "event":"tuto-2\/logout", - "data":"jobol", - "jtype":"afb-event" -} -``` diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/3_Binder_References.md b/docs/3_Developer_Guides/2_Application_Framework_Binder/3_Binder_References.md deleted file mode 100644 index fab571b..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/3_Binder_References.md +++ /dev/null @@ -1,2524 +0,0 @@ ---- -title: Binder References ---- - -i. TYPES AND GLOBALS -====================== - -## The global afbBindingRoot - -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. - -When the binding has a defined **afbBindingExport**, the root api -**afbBindingRoot** is the **afb_pi_t** relative to the api created for -this static description. - -When the binding has no defined **afbBindingExport**, the root api is -a virtual api representing the shared object of the binding. In that case -the name of the api is the path of the shared object. Its use is restricted -but allows log messages. - -## The global afbBindingExport - -The global **afbBindingExport** is not mandatory. - -If **afbBindingExport** is defined and exported, it must be of the type -**const afb_binding_t** and must describe the *root* api of the binding. - -## The type afb_api_t - -Bindings now can declare more than one api. The counter part is that -a new handle is needed to manage apis. These handles are of the type -**afb_api_t**. - -It is defined as below. - -```C -typedef struct afb_api_x3 afb_api_t; -``` - -## The type afb_binding_t - -The main structure, of type **afb_binding_t**, for describing the binding -must be exported under the name **afbBindingExport**. - -This structure is defined as below. - -```C -typedef struct afb_binding_v3 afb_binding_t; -``` - -Where: - -```C -/** - * Description of the bindings of type version 3 - */ -struct afb_binding_v3 -{ - /** api name for the binding, can't be NULL */ - const char *api; - - /** textual specification of the binding, can be NULL */ - const char *specification; - - /** some info about the api, can be NULL */ - const char *info; - - /** array of descriptions of verbs terminated by a NULL name, can be NULL */ - const struct afb_verb_v3 *verbs; - - /** callback at load of the binding */ - int (*preinit)(struct afb_api_x3 *api); - - /** callback for starting the service */ - int (*init)(struct afb_api_x3 *api); - - /** callback for handling events */ - void (*onevent)(struct afb_api_x3 *api, const char *event, struct json_object *object); - - /** userdata for afb_api_x3 */ - void *userdata; - - /** space separated list of provided class(es) */ - const char *provide_class; - - /** space separated list of required class(es) */ - const char *require_class; - - /** space separated list of required API(es) */ - const char *require_api; - - /** avoids concurrent requests to verbs */ - unsigned noconcurrency: 1; -}; -``` - -## The type afb_verb_t - -Each verb is described with a structure of type **afb_verb_t** -defined below: - -```C -typedef struct afb_verb_v3 afb_verb_t; -``` - -```C -/** - * Description of one verb as provided for binding API version 3 - */ -struct afb_verb_v3 -{ - /** name of the verb, NULL only at end of the array */ - const char *verb; - - /** callback function implementing the verb */ - void (*callback)(afb_req_t_x2 *req); - - /** required authorization, can be NULL */ - const struct afb_auth *auth; - - /** some info about the verb, can be NULL */ - const char *info; - - /**< data for the verb callback */ - void *vcbdata; - - /** authorization and session requirements of the verb */ - uint16_t session; - - /** is the verb glob name */ - uint16_t glob: 1; -}; -``` - -The **session** flags is one of the constant defined below: - -| Name | Description -|:----------------------:|------------------------------------------------------ -| 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 closing the session after request processed - -The LOA (Level Of Assurance) is set, by binding api, using the function **afb_req_session_set_LOA**. - -The session can be closed, by binding api, using the function **afb_req_session_close**. - -## The types afb_auth_t and afb_auth_type_t - -The structure **afb_auth_t** is used within verb description to -set security requirements. -The interpretation of the structure depends on the value of the field **type**. - -```C -typedef struct afb_auth afb_auth_t; - -/** - * Definition of an authorization entry - */ -struct afb_auth -{ - /** type of entry @see afb_auth_type */ - enum afb_auth_type type; - - union { - /** text when @ref type == @ref afb_auth_Permission */ - const char *text; - - /** level of assurancy when @ref type == @ref afb_auth_LOA */ - unsigned loa; - - /** first child when @ref type in { @ref afb_auth_Or, @ref afb_auth_And, @ref afb_auth_Not } */ - const struct afb_auth *first; - }; - - /** second child when @ref type in { @ref afb_auth_Or, @ref afb_auth_And } */ - const struct afb_auth *next; -}; - -``` - -The possible values for **type** is defined here: - -```C -typedef enum afb_auth_type afb_auth_type_t; - -/** - * Enumeration for authority (Session/Token/Assurance) definitions. - * - * @see afb_auth - */ -enum afb_auth_type -{ - /** never authorized, no data */ - afb_auth_No = 0, - - /** authorized if token valid, no data */ - afb_auth_Token, - - /** authorized if LOA greater than or equal to data 'loa' */ - afb_auth_LOA, - - /** authorized if permission 'text' is granted */ - afb_auth_Permission, - - /** authorized if 'first' or 'next' is authorized */ - afb_auth_Or, - - /** authorized if 'first' and 'next' are authorized */ - afb_auth_And, - - /** authorized if 'first' is not authorized */ - afb_auth_Not, - - /** always authorized, no data */ - afb_auth_Yes -}; -``` - -Example: - -```C -static const afb_auth_t myauth[] = { - { .type = afb_auth_Permission, .text = "urn:AGL:permission:me:public:set" }, - { .type = afb_auth_Permission, .text = "urn:AGL:permission:me:public:get" }, - { .type = afb_auth_Or, .first = &myauth[1], .next = &myauth[0] } -}; -``` - - -## The type afb_req_subcall_flags_t - -This is an enumeration that defines bit's positions for setting behaviour -of subcalls. - -| flag | value | description -|----------------------------|-------|-------------- -| afb_req_subcall_catch_events | 1 | the calling API wants to receive the events from subscription -| afb_req_subcall_pass_events | 2 | the original request will receive the events from subscription -| afb_req_subcall_on_behalf | 4 | the calling API wants to use the credentials of the original request -| afb_req_subcall_api_session | 8 | the calling API wants to use its session instead of the one of the original request - -ii. MACROS FOR LOGGING -================= - -The final behaviour of macros can be tuned using 2 defines that must be defined -before including ****. - -| define | action -|---------------------------------------|-------------------- -| AFB_BINDING_PRAGMA_NO_VERBOSE_DATA | show file and line, remove function and text message -| AFB_BINDING_PRAGMA_NO_VERBOSE_DETAILS | show text, remove function, line and file - -## Logging for an api - -The following macros must be used for logging for an **api** of type -**afb_api_t**. - -```C -AFB_API_ERROR(api,fmt,...) -AFB_API_WARNING(api,fmt,...) -AFB_API_NOTICE(api,fmt,...) -AFB_API_INFO(api,fmt,...) -AFB_API_DEBUG(api,fmt,...) -``` - -## Logging for a request - - -The following macros can be used for logging in the context -of a request **req** of type **afb_req_t**: - -```C -AFB_REQ_ERROR(req,fmt,...) -AFB_REQ_WARNING(req,fmt,...) -AFB_REQ_NOTICE(req,fmt,...) -AFB_REQ_INFO(req,fmt,...) -AFB_REQ_DEBUG(req,fmt,...) -``` - -By default, the logging macros add file, line and function -indication. - -## Logging legacy - -The following macros are provided for legacy. - -```C -AFB_ERROR(fmt,...) -AFB_WARNING(fmt,...) -AFB_NOTICE(fmt,...) -AFB_INFO(fmt,...) -AFB_DEBUG(fmt,...) -``` - -iii. FUNCTIONS OF CLASS **afb_api** -============================ - -## General functions - -### afb_api_name - -```C -/** - * Get the name of the 'api'. - * - * @param api the api whose name is to be returned - * - * @return the name of the api. - * - * The returned value must not be changed nor freed. - */ -const char *afb_api_name( - afb_api_t api); -``` - -### afb_api_get_userdata - -```C -/** - * Get the "userdata" pointer of the 'api' - * - * @param api the api whose user's data is to be returned - * - * @return the user's data pointer of the api. - * - * @see afb_api_set_userdata - */ -void *afb_api_get_userdata( - afb_api_t api); -``` - -### afb_api_set_userdata - -```C -/** - * Set the "userdata" pointer of the 'api' to 'value' - * - * @param api the api whose user's data is to be set - * @param value the data to set - * - * @see afb_api_get_userdata - */ -void afb_api_set_userdata( - afb_api_t api, - void *value); -``` - -### afb_api_require_api - -```C -/** - * Check that it requires the API of 'name'. - * 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. - * - * A single request allows to require multiple apis. - * - * @param api the api that requires the other api by its name - * @param name a space separated list of required api names - * @param initialized if zero, the api is just required to exist. If not zero, - * the api is required to exist and to be initialized at return of the call - * (initializing it if needed and possible as a side effect of the call). - * - * @return 0 in case of success or -1 in case of error with errno set appropriately. - */ -int afb_api_require_api( - afb_api_t api, - const char *name, - int initialized); -``` - - -## Verbosity functions - -### afb_api_wants_log_level - -```C -/** - * Is the log message of 'level (as defined for syslog) required for the api? - * - * @param api the api to check - * @param level the level to check as defined for syslog: - * - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - * - * @return 0 if not required or a value not null if required - * - * @see syslog - */ -int afb_api_wants_log_level( - afb_api_t api, - int level); -``` - -### afb_api_vverbose - -```C -/** - * Send to the journal with the logging 'level' a message described - * by 'fmt' applied to the va-list 'args'. - * - * 'file', 'line' and 'func' are indicators of code position in source files - * (see macros __FILE__, __LINE__ and __func__). - * - * 'level' is defined by syslog standard: - * - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - * - * @param api the api that collects the logging message - * @param level the level of the message - * @param file the source file that logs the messages or NULL - * @param line the line in the source file that logs the message - * @param func the name of the function in the source file that logs - * @param fmt the format of the message as in printf - * @param args the arguments to the format string of the message as a va_list - * - * @see syslog - * @see printf - */ -void afb_api_vverbose( - afb_api_t api, - int level, - const char *file, - int line, - const char *func, - const char *fmt, - va_list args); -``` - -### afb_api_verbose - -```C -/** - * Send to the journal with the log 'level' a message described - * by 'fmt' and following parameters. - * - * 'file', 'line' and 'func' are indicators of position of the code in source files - * (see macros __FILE__, __LINE__ and __func__). - * - * 'level' is defined by syslog standard: - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - * - * @param api the api that collects the logging message - * @param level the level of the message - * @param file the source file that logs the messages or NULL - * @param line the line in the source file that logs the message - * @param func the name of the function in the source file that logs - * @param fmt the format of the message as in printf - * @param ... the arguments to the format string of the message - * - * @see syslog - * @see printf - */ -void afb_api_verbose( - afb_api_t api, - int level, - const char *file, - int line, - const char *func, - const char *fmt, - ...); -``` - -## Data retrieval functions - -### afb_api_rootdir_get_fd - -```C -/** - * Get the root directory file descriptor. This file descriptor can - * be used with functions 'openat', 'fstatat', ... - * - * 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: - * - * char buffer[MAX_PATH], proc[100]; - * int dirfd = afb_api_rootdir_get_fd(api); - * snprintf(proc, sizeof proc, "/proc/self/fd/%d", dirfd); - * readlink(proc, buffer, sizeof buffer); - * - * But note that within AGL this is the value given by the environment variable - * AFM_APP_INSTALL_DIR. - * - * @param api the api that uses the directory file descriptor - * - * @return the file descriptor of the root directory. - * - * @see afb_api_rootdir_open_locale - */ -int afb_api_rootdir_get_fd( - afb_api_t api); -``` - -### afb_api_rootdir_open_locale - -```C -/** - * Opens 'filename' within the root directory with 'flags' (see function openat) - * using the 'locale' definition (example: "jp,en-US") that can be NULL. - * - * The filename must be relative to the root of the bindings. - * - * The opening mode must be for read or write but not for O_CREAT. - * - * The definition of locales and of how files are searched can be checked - * here: https://www.w3.org/TR/widgets/#folder-based-localization - * and https://tools.ietf.org/html/rfc7231#section-5.3.5 - * - * @param api the api that queries the file - * @param filename the relative path to the file to open - * @param flags the flags for opening as for C function 'open' - * @param locale string indicating how to search content, can be NULL - * - * @return the file descriptor or -1 in case of error and errno is set with the - * error indication. - * - * @see open - * @see afb_api_rootdir_get_fd - */ -int afb_api_rootdir_open_locale( - afb_api_t api, - const char *filename, - int flags, - const char *locale); -``` - -### afb_api_settings - -```C -/** - * Settings of the api. - * - * Get the settings of the API. The settings are recorded - * as a JSON object. The returned object should not be modified. - * It MUST NOT be released using json_object_put. - * - * @param api the api whose settings are required - * - * @returns The setting object. - */ -struct json_object *afb_api_settings( - struct afb_api_x3 *api); -``` - -## Calls and job functions - -### afb_api_call - -```C -/** - * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'. - * The result of the call is delivered to the 'callback' function with the 'callback_closure'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * The 'callback' receives 5 arguments: - * 1. 'closure' the user defined closure pointer 'closure', - * 2. 'object' a JSON object returned (can be NULL) - * 3. 'error' a string not NULL in case of error but NULL on success - * 4. 'info' a string handling some info (can be NULL) - * 5. 'api' the api - * - * NOTE: For convenience, *json_object_put* is called on 'object' after the - * callback returns. So, it is wrong to call *json_object_put* in the callback. - * - * @param api The api that makes the call - * @param apiname The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param callback The to call on completion - * @param closure The closure to pass to the callback - * - * - * @see afb_req_subcall - * @see afb_req_subcall_sync - * @see afb_api_call_sync - */ -void afb_api_call( - afb_api_t api, - const char *apiname, - const char *verb, - struct json_object *args, - void (*callback)( - void *closure, - struct json_object *object, - const char *error, - const char * info, - afb_api_t api), - void *closure); -``` - -### afb_api_call_sync - -```C -/** - * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'. - * 'result' will receive the response. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param api The api that makes the call - * @param apiname The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param object Where to store the returned object - should call json_object_put on it - can be NULL - * @param error Where to store the copied returned error - should call free on it - can be NULL - * @param info Where to store the copied returned info - should call free on it - can be NULL - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see afb_req_subcall - * @see afb_req_subcall_sync - * @see afb_api_call - */ -int afb_api_call_sync( - afb_api_t api, - const char *apiname, - const char *verb, - struct json_object *args, - struct json_object **object, - char **error, - char **info); -``` - -### afb_api_queue_job - -```C -/** - * Queue the job defined by 'callback' and 'argument' for being executed asynchronously - * in this thread (later) or in an other thread. - * - * If 'group' is not NULL, the jobs queued with a same value (as the pointer value 'group') - * are executed in sequence in the order of there submission. - * - * If 'timeout' is not 0, it represent the maximum execution time for the job in seconds. - * At first, the job is called with 0 as signum and the given argument. - * - * The job is executed with the monitoring of its time and some signals like SIGSEGV and - * SIGFPE. When a such signal is catched, the job is terminated and reexecuted but with - * signum being the signal number (SIGALRM when timeout expired). - * - * When executed, the callback function receives 2 arguments: - * - * - int signum: the signal catched if any or zero at the beginning - * - void *arg: the parameter 'argument' - * - * A typical implementation of the job callback is: - * - * void my_job_cb(int signum, void *arg) - * { - * struct myarg_t *myarg = arg; - * if (signum) - * AFB_API_ERROR(myarg->api, "job interrupted with signal %s", strsignal(signum)); - * else - * really_do_my_job(myarg); - * } - * - * @param api the api that queue the job - * @param callback the job as a callback function - * @param argument the argument to pass to the queued job - * @param group the group of the job, NULL if no group - * @param timeout the timeout of execution of the job - * - * @return 0 in case of success or -1 in case of error with errno set appropriately. - */ -int afb_api_queue_job( - afb_api_t api, - void (*callback)(int signum, void *arg), - void *argument, - void *group, - int timeout); -``` - -## Event functions - -### afb_api_broadcast_event - -```C -/** - * Broadcasts widely the event of 'name' with the data 'object'. - * 'object' can be NULL. - * - * For convenience, the function calls 'json_object_put' for 'object'. - * Thus, in the case where 'object' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * Calling this function is only forbidden during preinit. - * - * The event sent as the name API/name where API is the name of the - * api. - * - * @param api the api that broadcast the event - * @param name the event name suffix - * @param object the object that comes with the event - * - * @return 0 in case of success or -1 in case of error - */ -int afb_api_broadcast_event( - afb_api_t api, - const char *name, - struct json_object *object); -``` - -### afb_api_make_event - -```C -/** - * Creates an event of 'name' and returns it. - * - * Calling this function is only forbidden during preinit. - * - * See afb_event_is_valid to check if there is an error. - * - * The event created as the name API/name where API is the name of the - * api. - * - * @param api the api that creates the event - * @param name the event name suffix - * - * @return the created event. Use the function afb_event_is_valid to check - * whether the event is valid (created) or not (error as reported by errno). - * - * @see afb_event_is_valid - */ -afb_event_t afb_api_make_event( - afb_api_t api, - const char *name); -``` - -### afb_api_event_handler_add - -```C -/** - * Add a specific event handler for the api - * - * The handler callback is called when an event matching the given pattern - * is received (it is received if broadcasted or after subscription through - * a call or a subcall). - * - * The handler callback receive 4 arguments: - * - * - the closure given here - * - the event full name - * - the companion JSON object of the event - * - the api that subscribed the event - * - * @param api the api that creates the handler - * @param pattern the global pattern of the event to handle - * @param callback the handler callback function - * @param closure the closure of the handler - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afb_api_on_event - * @see afb_api_event_handler_del - */ -int afb_api_event_handler_add( - afb_api_t api, - const char *pattern, - void (*callback)( - void *, - const char*, - struct json_object*, - afb_api_t), - void *closure); -``` - -### afb_api_event_handler_del - -```C -/** - * Delete a specific event handler for the api - * - * @param api the api that the handler belongs to - * @param pattern the global pattern of the handler to remove - * @param closure if not NULL it will receive the closure set to the handler - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afb_api_on_event - * @see afb_api_event_handler_add - */ -int afb_api_event_handler_del( - afb_api_t api, - const char *pattern, - void **closure); - -``` - -## Systemd functions - -### afb_api_get_event_loop - -```C -/** - * Retrieves the common systemd's event loop of AFB - * - * @param api the api that uses the event loop - * - * @return the systemd event loop if active, NULL otherwise - * - * @see afb_api_get_user_bus - * @see afb_api_get_system_bus - */ -struct sd_event *afb_api_get_event_loop( - afb_api_t api); -``` - -### afb_api_get_user_bus - -```C -/** - * Retrieves the common systemd's user/session d-bus of AFB - * - * @param api the api that uses the user dbus - * - * @return the systemd user connection to dbus if active, NULL otherwise - * - * @see afb_api_get_event_loop - * @see afb_api_get_system_bus - */ -struct sd_bus *afb_api_get_user_bus( - afb_api_t api); -``` - -### afb_api_get_system_bus - -```C -/** - * Retrieves the common systemd's system d-bus of AFB - * - * @param api the api that uses the system dbus - * - * @return the systemd system connection to dbus if active, NULL otherwise - * - * @see afb_api_get_event_loop - * @see afb_api_get_user_bus - */ -struct sd_bus *afb_api_get_system_bus( - afb_api_t api); -``` - - -## Dynamic api functions - -### afb_api_new_api - -```C -/** - * Creates a new api of name 'apiname' briefly described by 'info' (that can - * be NULL). - * - * When the pre-initialization function is given, it is a function that - * receives 2 parameters: - * - * - the closure as given in the call - * - the created api that can be initialised - * - * This pre-initialization function must return a negative value to abort - * the creation of the api. Otherwise, it returns a non-negative value to - * continue. - * - * @param api the api that creates the other one - * @param apiname the name of the new api - * @param info the brief description of the new api (can be NULL) - * @param noconcurrency zero or not zero whether the new api is reentrant or not - * @param preinit the pre-initialization function if any (can be NULL) - * @param closure the closure for the pre-initialization preinit - * - * @return the created api in case of success or NULL on error - * - * @see afb_api_delete_api - */ -afb_api_t afb_api_new_api( - afb_api_t api, - const char *apiname, - const char *info, - int noconcurrency, - int (*preinit)(void*, afb_api_t ), - void *closure); -``` - -### afb_api_set_verbs_v2 - -```C -/** - * @deprecated use @ref afb_api_set_verbs_v3 instead - * - * Set the verbs of the 'api' using description of verbs of the api v2 - * - * @param api the api that will get the verbs - * @param verbs the array of verbs to add terminated with an item with name=NULL - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afb_verb_v2 - * @see afb_api_add_verb - * @see afb_api_set_verbs_v3 - */ -int afb_api_set_verbs_v2( - afb_api_t api, - const struct afb_verb_v2 *verbs); -``` - -### afb_api_set_verbs_v3 - -```C -/** - * Set the verbs of the 'api' using description of verbs of the api v2 - * - * @param api the api that will get the verbs - * @param verbs the array of verbs to add terminated with an item with name=NULL - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afb_verb_v3 - * @see afb_api_add_verb - * @see afb_api_del_verb - */ -int afb_api_set_verbs_v3( - afb_api_t api, - const struct afb_verb_v3 *verbs); -``` - -### afb_api_add_verb - -```C -/** - * Add one verb to the dynamic set of the api - * - * @param api the api to change - * @param verb name of the verb - * @param info brief description of the verb, can be NULL - * @param callback callback function implementing the verb - * @param vcbdata data for the verb callback, available through req - * @param auth required authorization, can be NULL - * @param session authorization and session requirements of the verb - * @param glob is the verb glob name - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afb_verb_v3 - * @see afb_api_del_verb - * @see afb_api_set_verbs_v3 - * @see fnmatch for matching names using glob - */ -int afb_api_add_verb( - afb_api_t api, - const char *verb, - const char *info, - void (*callback)(struct afb_req_x2 *req), - void *vcbdata, - const struct afb_auth *auth, - uint32_t session, - int glob); -``` - -### afb_api_del_verb - -```C -/** - * Delete one verb from the dynamic set of the api - * - * @param api the api to change - * @param verb name of the verb to delete - * @param vcbdata if not NULL will receive the vcbdata of the deleted verb - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afb_api_add_verb - */ -int afb_api_del_verb( - afb_api_t api, - const char *verb, - void **vcbdata); -``` - -### afb_api_on_event - -```C -/** - * Set the callback 'onevent' to process events in the name of the 'api'. - * - * This setting can be done statically using the global variable - * @ref afbBindingV3. - * - * This function replace any previously global event callback set. - * - * When an event is received, the callback 'onevent' is called with 3 parameters - * - * - the api that recorded the event handler - * - the full name of the event - * - the companion JSON object of the event - * - * @param api the api that wants to process events - * @param onevent the callback function that will process events (can be NULL - * to remove event callback) - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afbBindingV3 - * @see afb_binding_v3 - * @see afb_api_event_handler_add - * @see afb_api_event_handler_del - */ -int afb_api_on_event( - afb_api_t api, - void (*onevent)( - afb_api_t api, - const char *event, - struct json_object *object)); -``` - -### afb_api_on_init - -```C -/** - * Set the callback 'oninit' to process initialization of the 'api'. - * - * This setting can be done statically using the global variable - * @ref afbBindingV3 - * - * This function replace any previously initialization callback set. - * - * This function is only valid during the pre-initialization stage. - * - * The callback initialization function will receive one argument: the api - * to initialize. - * - * @param api the api that wants to process events - * @param oninit the callback function that initialize the api - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afbBindingV3 - * @see afb_binding_v3 - */ -int afb_api_on_init( - afb_api_t api, - int (*oninit)(afb_api_t api)); -``` - -### afb_api_provide_class - -```C -/** - * Tells that the api provides a class of features. Classes are intended to - * allow ordering of initializations: apis that provides a given class are - * initialized before apis requiring it. - * - * This function is only valid during the pre-initialization stage. - * - * @param api the api that provides the classes - * @param name a space separated list of the names of the provided classes - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see afb_api_require_class - */ -int afb_api_provide_class( - afb_api_t api, - const char *name); -``` - -### afb_api_require_class - -```C -/** - * Tells that the api requires a set of class features. Classes are intended to - * allow ordering of initializations: apis that provides a given class are - * initialized before apis requiring it. - * - * This function is only valid during the pre-initialization stage. - * - * @param api the api that requires the classes - * @param name a space separated list of the names of the required classes - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see afb_api_provide_class - */ -int afb_api_require_class( - afb_api_t api, - const char *name); -``` - -### afb_api_seal - -```C -/** - * Seal the api. After a call to this function the api can not be modified - * anymore. - * - * @param api the api to be sealed - */ -void afb_api_seal( - afb_api_t api); -``` - -### afb_api_delete_api - -```C -/** - * Delete the given api. - * - * It is of the responsibility of the caller to don't used the deleted api - * anymore after this function returned. - * - * @param api the api to delete - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see afb_api_new_api - */ -int afb_api_delete_api( - afb_api_t api); -``` - -### afb_api_add_alias - -```C -/** - * Create an aliased name 'as_name' for the api 'name'. - * Calling this function is only allowed within preinit. - * - * @param api the api that requires the aliasing - * @param name the api to alias - * @param as_name the aliased name of the aliased api - * - * @return 0 in case of success or -1 in case of error with errno set appropriately. - */ -int afb_api_add_alias( - afb_api_t api, - const char *name, - const char *as_name); -``` - - -## Legacy functions - -The function for legacy calls are still provided for some time because -adaptation of existing code to the new call functions require a small amount -of work. - -### afb_api_call_legacy - -```C -/** - * @deprecated try to use @ref afb_api_call instead - * - * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' - * in the name of the binding. - * The result of the call is delivered to the 'callback' function - * with the 'callback_closure'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * The 'callback' receives 3 arguments: - * 1. 'closure' the user defined closure pointer 'closure', - * 2. 'status' a status being 0 on success or negative when an error occurred, - * 2. 'result' the resulting data as a JSON object. - * - * @param api The api - * @param apiname The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param callback The to call on completion - * @param closure The closure to pass to the callback - * - * @see also 'afb_api_call' - * @see also 'afb_api_call_sync' - * @see also 'afb_api_call_sync_legacy' - * @see also 'afb_req_subcall' - * @see also 'afb_req_subcall_sync' - */ -void afb_api_call_legacy( - afb_api_t api, - const char *apiname, - const char *verb, - struct json_object *args, - void (*callback)( - void *closure, - int status, - struct json_object *result, - afb_api_t api), - void *closure); -``` - -### afb_api_call_sync_legacy - -```C -/** - * @deprecated try to use @ref afb_api_call_sync instead - * - * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' - * in the name of the binding. - * 'result' will receive the response. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param api The api - * @param apiname The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param result Where to store the result - should call json_object_put on it - - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see also 'afb_api_call' - * @see also 'afb_api_call_sync' - * @see also 'afb_api_call_legacy' - * @see also 'afb_req_subcall' - * @see also 'afb_req_subcall_sync' - */ -int afb_api_call_sync_legacy( - afb_api_t api, - const char *apiname, - const char *verb, - struct json_object *args, - struct json_object **result); -``` - -iv. FUNCTIONS OF CLASS **afb_req** -============================ - -## General function - -### afb_req_is_valid - -```C -/** - * Checks whether the request 'req' is valid or not. - * - * @param req the request to check - * - * @return 0 if not valid or 1 if valid. - */ -int afb_req_is_valid( - afb_req_t req); -``` - -### afb_req_get_api - -```C -/** - * Retrieves the api that serves the request - * - * @param req the request whose serving api is queried - * - * @return the api serving the request - */ -afb_api_t afb_req_get_api( - afb_req_t req); -``` - -### afb_req_get_vcbdata - -```C -/** - * Retrieves the callback data of the verb. This callback data is set - * when the verb is created. - * - * @param req whose verb vcbdata is queried - * - * @return the callback data attached to the verb description - */ -void *afb_req_get_vcbdata( - afb_req_t req); -``` - -### afb_req_get_called_api - -```C -/** - * Retrieve the name of the called api. - * - * @param req the request - * - * @return the name of the called api - * - * @see afb_api_new_api - * @see afb_api_add_alias - */ -const char *afb_req_get_called_api( - afb_req_t req); -``` - -### afb_req_get_called_verb - -```C -/** - * Retrieve the name of the called verb - * - * @param req the request - * - * @return the name of the called verb - */ -const char *afb_req_get_called_verb( - afb_req_t req); -``` - -### afb_req_addref - -```C -/** - * Increments the count of references of 'req'. - * - * @param req the request - * - * @return returns the request req - */ -afb_req_t *afb_req_addref( - afb_req_t req); -``` - -### afb_req_unref - -```C -/** - * Decrement the count of references of 'req'. - * - * @param req the request - */ -void afb_req_unref( - afb_req_t req); -``` - - -## Logging functions - -### afb_req_wants_log_level - -```C -/** - * Is the log message of 'level (as defined for syslog) required for the - * request 'req'? - * - * @param req the request - * @param level the level to check as defined for syslog: - * - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - * - * @return 0 if not required or a value not null if required - * - * @see syslog - */ -int afb_req_wants_log_level( - afb_req_t req, - int level); -``` - -### afb_req_vverbose - -```C -/** - * Send associated to 'req' a message described by 'fmt' and its 'args' - * to the journal for the verbosity 'level'. - * - * 'file', 'line' and 'func' are indicators of position of the code in source files - * (see macros __FILE__, __LINE__ and __func__). - * - * 'level' is defined by syslog standard: - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - * - * @param req the request - * @param level the level of the message - * @param file the source filename that emits the message or NULL - * @param line the line number in the source filename that emits the message - * @param func the name of the function that emits the message or NULL - * @param fmt the message format as for printf - * @param args the arguments to the format - * - * @see printf - * @see afb_req_verbose - */ -void afb_req_vverbose( - afb_req_t req, - int level, const char *file, - int line, - const char * func, - const char *fmt, - va_list args); -``` - -### afb_req_verbose - -```C -/** - * Send associated to 'req' a message described by 'fmt' and following parameters - * to the journal for the verbosity 'level'. - * - * 'file', 'line' and 'func' are indicators of position of the code in source files - * (see macros __FILE__, __LINE__ and __func__). - * - * 'level' is defined by syslog standard: - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - * - * @param req the request - * @param level the level of the message - * @param file the source filename that emits the message or NULL - * @param line the line number in the source filename that emits the message - * @param func the name of the function that emits the message or NULL - * @param fmt the message format as for printf - * @param ... the arguments of the format 'fmt' - * - * @see printf - */ -void afb_req_verbose( - afb_req_t req, - int level, const char *file, - int line, - const char * func, - const char *fmt, - ...); -``` - -## Arguments/parameters function - -### afb_req_get - -```C -/** - * Gets from the request 'req' the argument of 'name'. - * - * Returns a PLAIN structure of type 'struct afb_arg'. - * - * When the argument of 'name' is not found, all fields of result are set to NULL. - * - * When the argument of 'name' is found, the fields are filled, - * in particular, the field 'result.name' is set to 'name'. - * - * There is a special name value: the empty string. - * The argument of name "" is defined only if the request was made using - * an HTTP POST of Content-Type "application/json". In that case, the - * argument of name "" receives the value of the body of the HTTP request. - * - * @param req the request - * @param name the name of the argument to get - * - * @return a structure describing the retrieved argument for the request - * - * @see afb_req_value - * @see afb_req_path - */ -struct afb_arg afb_req_get( - afb_req_t req, - const char *name); -``` - -### afb_req_value - -```C -/** - * Gets from the request 'req' the string value of the argument of 'name'. - * Returns NULL if when there is no argument of 'name'. - * Returns the value of the argument of 'name' otherwise. - * - * Shortcut for: afb_req_get(req, name).value - * - * @param req the request - * @param name the name of the argument's value to get - * - * @return the value as a string or NULL - * - * @see afb_req_get - * @see afb_req_path - */ -const char *afb_req_value( - afb_req_t req, - const char *name); -``` - -### afb_req_path - -```C -/** - * Gets from the request 'req' the path for file attached to the argument of 'name'. - * Returns NULL if when there is no argument of 'name' or when there is no file. - * Returns the path of the argument of 'name' otherwise. - * - * Shortcut for: afb_req_get(req, name).path - * - * @param req the request - * @param name the name of the argument's path to get - * - * @return the path if any or NULL - * - * @see afb_req_get - * @see afb_req_value - */ -const char *afb_req_path( - afb_req_t req, - const char *name); -``` - -### afb_req_json - -```C -/** - * Gets from the request 'req' the json object hashing the arguments. - * - * The returned object must not be released using 'json_object_put'. - * - * @param req the request - * - * @return the JSON object of the query - * - * @see afb_req_get - * @see afb_req_value - * @see afb_req_path - */ -struct json_object *afb_req_json( - afb_req_t req); -``` - -## Reply functions - -The functions **success** and **fail** are still supported. -These functions are now implemented as the following macros: - -```C -#define afb_req_success(r,o,i) afb_req_reply(r,o,NULL,i) -#define afb_req_success_f(r,o,...) afb_req_reply_f(r,o,NULL,__VA_ARGS__) -#define afb_req_success_v(r,o,f,v) afb_req_reply_v(r,o,NULL,f,v) -#define afb_req_fail(r,e,i) afb_req_reply(r,NULL,e,i) -#define afb_req_fail_f(r,e,...) afb_req_reply_f(r,NULL,e,__VA_ARGS__) -#define afb_req_fail_v(r,e,f,v) afb_req_reply_v(r,NULL,e,f,v) -``` - - -### afb_req_reply - -```C -/** - * Sends a reply to the request 'req'. - * - * The status of the reply is set to 'error' (that must be NULL on success). - * Its send the object 'obj' (can be NULL) with an - * informational comment 'info (can also be NULL). - * - * For convenience, the function calls 'json_object_put' for 'obj'. - * Thus, in the case where 'obj' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param req the request - * @param obj the replied object or NULL - * @param error the error message if it is a reply error or NULL - * @param info an informative text or NULL - * - * @see afb_req_reply_v - * @see afb_req_reply_f - */ -void afb_req_reply( - afb_req_t req, - struct json_object *obj, - const char *error, - const char *info); -``` - -### afb_req_reply_v - -```C -/** - * Same as 'afb_req_reply_f' but the arguments to the format 'info' - * are given as a variable argument list instance. - * - * For convenience, the function calls 'json_object_put' for 'obj'. - * Thus, in the case where 'obj' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param req the request - * @param obj the replied object or NULL - * @param error the error message if it is a reply error or NULL - * @param info an informative text containing a format as for vprintf - * @param args the va_list of arguments to the format as for vprintf - * - * @see afb_req_reply - * @see afb_req_reply_f - * @see vprintf - */ -void afb_req_reply_v( - afb_req_t req, - struct json_object *obj, - const char *error, - const char *info, - va_list args); -``` - -### afb_req_reply_f - -```C -/** - * Same as 'afb_req_reply' but the 'info' is a formatting - * string followed by arguments. - * - * For convenience, the function calls 'json_object_put' for 'obj'. - * Thus, in the case where 'obj' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param req the request - * @param obj the replied object or NULL - * @param error the error message if it is a reply error or NULL - * @param info an informative text containing a format as for printf - * @param ... the arguments to the format as for printf - * - * @see afb_req_reply - * @see afb_req_reply_v - * @see printf - */ -void afb_req_reply_f( - afb_req_t req, - struct json_object *obj, - const char *error, - const char *info, - ...); -``` - -## Subcall functions - - - -### afb_req_subcall - -```C -/** - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. - * The result of the call is delivered to the 'callback' function with the 'callback_closure'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * The 'callback' receives 5 arguments: - * 1. 'closure' the user defined closure pointer 'closure', - * 2. 'object' a JSON object returned (can be NULL) - * 3. 'error' a string not NULL in case of error - * 4. 'info' a string handling some info (can be NULL) - * 5. 'req' the req - * - * NOTE: For convenience, *json_object_put* is called on 'object' after the - * callback returns. So, it is wrong to call *json_object_put* in the callback. - * - * @param req The request - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param flags The bit field of flags for the subcall as defined by @ref afb_req_subcall_flags_t - * @param callback The to call on completion - * @param closure The closure to pass to the callback - * - * The flags are any combination of the following values: - * - * - afb_req_x2_subcall_catch_events = 1 - * - * the calling API wants to receive the events from subscription - * - * - afb_req_x2_subcall_pass_events = 2 - * - * the original request will receive the events from subscription - * - * - afb_req_x2_subcall_on_behalf = 4 - * - * the calling API wants to use the credentials of the original request - * - * - afb_req_x2_subcall_api_session = 8 - * - * the calling API wants to use its session instead of the one of the - * original request - * - * @see also 'afb_req_subcall_sync' - */ -void afb_req_subcall( - afb_req_t req, - const char *api, - const char *verb, - struct json_object *args, - int flags, - void (*callback)( - void *closure, - struct json_object *object, - const char *error, - const char * info, - afb_req_t req), - void *closure); -``` - -### afb_req_subcall_sync - -```C -/** - * 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. - * It returns 0 on success or a negative value on error answer. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * See also: - * - 'afb_req_subcall_req' that is convenient to keep request alive automatically. - * - 'afb_req_subcall' that doesn't keep request alive automatically. - * - * @param req The request - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param flags The bit field of flags for the subcall as defined by @ref afb_req_subcall_flags - * @param object a pointer where the replied JSON object is stored must be freed using @ref json_object_put (can be NULL) - * @param error a pointer where a copy of the replied error is stored must be freed using @ref free (can be NULL) - * @param info a pointer where a copy of the replied info is stored must be freed using @ref free (can be NULL) - * - * @return 0 in case of success or -1 in case of error - */ -int afb_req_subcall_sync( - afb_req_t req, - const char *api, - const char *verb, - struct json_object *args, - int flags, - struct json_object **object, - char **error, - char **info); -``` - -## Event functions - -### afb_req_subscribe - -```C -/** - * Establishes for the client link identified by 'req' a subscription - * to the 'event'. - * - * Establishing subscription MUST be called BEFORE replying to the request. - * - * @param req the request - * @param event the event to subscribe - * - * @return 0 in case of successful subscription or -1 in case of error. - */ -int afb_req_subscribe( - afb_req_t req, - afb_event_t event); -``` - -### afb_req_unsubscribe - -```C -/** - * Revokes the subscription established to the 'event' for the client - * link identified by 'req'. - * Returns 0 in case of successful subscription or -1 in case of error. - * - * Revoking subscription MUST be called BEFORE replying to the request. - * - * @param req the request - * @param event the event to revoke - * - * @return 0 in case of successful subscription or -1 in case of error. - */ -int afb_req_unsubscribe( - afb_req_t req, - afb_event_t event); -``` - -## Session functions - -### afb_req_context - -```C -/** - * Manage the pointer stored by the binding for the client session of 'req'. - * - * If no previous pointer is stored or if 'replace' is not zero, a new value - * is generated using the function 'create_context' called with the 'closure'. - * If 'create_context' is NULL the generated value is 'closure'. - * - * When a value is created, the function 'free_context' is recorded and will - * be called (with the created value as argument) to free the created value when - * it is not more used. - * - * This function is atomic: it ensures that 2 threads will not race together. - * - * @param req the request - * @param replace if not zero an existing value is replaced - * @param create_context the creation function or NULL - * @param free_context the destroying function or NULL - * @param closure the closure to the creation function - * - * @return the stored value - */ -void *afb_req_context( - afb_req_t req, - int replace, - void *(*create_context)(void *closure), - void (*free_context)(void*), - void *closure); -``` - -### afb_req_context_get - -```C -/** - * Gets the pointer stored by the binding for the session of 'req'. - * When the binding has not yet recorded a pointer, NULL is returned. - * - * Shortcut for: afb_req_context(req, 0, NULL, NULL, NULL) - * - * @param req the request - * - * @return the previously stored value - */ -void *afb_req_context_get( - afb_req_t req); -``` - -### afb_req_context_set - -```C -/** - * Stores for the binding the pointer 'context' to the session of 'req'. - * The function 'free_context' will be called when the session is closed - * or if binding stores an other pointer. - * - * Shortcut for: afb_req_context(req, 1, NULL, free_context, context) - * - * - * @param req the request - * @param context the context value to store - * @param free_context the cleaning function for the stored context (can be NULL) - */ -void afb_req_context_set( - afb_req_t req, - void *context, - void (*free_context)(void*)); -``` - -### afb_req_context_clear - -```C -/** - * Frees the pointer stored by the binding for the session of 'req' - * and sets it to NULL. - * - * Shortcut for: afb_req_context_set(req, NULL, NULL) - * - * @param req the request - */ -void afb_req_context_clear( - afb_req_t req); -``` - -### afb_req_session_close - -```C -/** - * Closes the session associated with 'req' - * and delete all associated contexts. - * - * @param req the request - */ -void afb_req_session_close( - afb_req_t req); -``` - -### afb_req_session_set_LOA - -```C -/** - * Sets the level of assurance of the session of 'req' - * to 'level'. The effect of this function is subject of - * security policies. - * - * @param req the request - * @param level of assurance from 0 to 7 - * - * @return 0 on success or -1 if failed. - */ -int afb_req_session_set_LOA( - afb_req_t req, - unsigned level); -``` - -## Credential/client functions - -### afb_req_has_permission - -```C -/** - * Check whether the 'permission' is granted or not to the client - * identified by 'req'. - * - * @param req the request - * @param permission string to check - * - * @return 1 if the permission is granted or 0 otherwise. - */ -int afb_req_has_permission( - afb_req_t req, - const char *permission); -``` - -### afb_req_get_application_id - -```C -/** - * Get the application identifier of the client application for the - * request 'req'. - * - * Returns the application identifier or NULL when the application - * can not be identified. - * - * The returned value if not NULL must be freed by the caller - * - * @param req the request - * - * @return the string for the application id of the client MUST BE FREED - */ -char *afb_req_get_application_id( - afb_req_t req); -``` - -### afb_req_get_uid - -```C -/** - * Get the user identifier (UID) of the client for the - * request 'req'. - * - * @param req the request - * - * @return -1 when the application can not be identified or the unix uid. - * - */ -int afb_req_get_uid( - afb_req_t req); -``` - -### afb_req_get_client_info - -```C -/** - * Get informations about the client of the - * request 'req'. - * - * Returns an object with client informations: - * { - * "pid": int, "uid": int, "gid": int, - * "label": string, "id": string, "user": string, - * "uuid": string, "LOA": int - * } - * - * If some of this information can't be computed, the field of the return - * object will not be set at all. - * - * @param req the request - * - * @return a JSON object that must be freed using @ref json_object_put - */ -struct json_object *afb_req_get_client_info( - afb_req_t req); -``` - -## Legacy functions - -### afb_req_subcall_legacy - -```C -/** - * @deprecated use @ref afb_req_subcall - * - * 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'. - * On completion, the function 'callback' is invoked with the - * 'closure' given at call and two other parameters: 'iserror' and 'result'. - * 'status' is 0 on success or negative when on an error reply. - * 'result' is the json object of the reply, you must not call json_object_put - * on the result. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param req the request - * @param api the name of the api to call - * @param verb the name of the verb to call - * @param args the arguments of the call as a JSON object - * @param callback the call back that will receive the reply - * @param closure the closure passed back to the callback - * - * @see afb_req_subcall - * @see afb_req_subcall_sync - */ -void afb_req_subcall_legacy( - afb_req_t req, - const char *api, - const char *verb, - struct json_object *args, - void (*callback)( - void *closure, - int iserror, - struct json_object *result, - afb_req_t req), - void *closure); -``` - -### afb_req_subcall_sync_legacy - -```C -/** - * @deprecated use @ref afb_req_subcall_sync - * - * 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 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'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param req the request - * @param api the name of the api to call - * @param verb the name of the verb to call - * @param args the arguments of the call as a JSON object - * @param result the pointer to the JSON object pointer that will receive the result - * - * @return 0 on success or a negative value on error answer. - * - * @see afb_req_subcall - * @see afb_req_subcall_sync - */ -int afb_req_subcall_sync_legacy( - afb_req_t req, - const char *api, - const char *verb, - struct json_object *args, - struct json_object **result); -``` - -v. FUNCTIONS OF CLASS **afb_event** -============================== - -## General functions - -### afb_event_is_valid - -```C -/** - * Checks whether the 'event' is valid or not. - * - * @param event the event to check - * - * @return 0 if not valid or 1 if valid. - */ -int afb_event_is_valid( - afb_event_t event); -``` - -### afb_event_name - -```C -/** - * Gets the name associated to 'event'. - * - * @param event the event whose name is requested - * - * @return the name of the event - * - * The returned name can be used until call to 'afb_event_unref'. - * It shouldn't be freed. - */ -const char *afb_event_name( - afb_event_t event); -``` - -### afb_event_unref - -```C -/** - * Decrease the count of references to 'event'. - * Call this function when the evenid is no more used. - * It destroys the event_x2 when the reference count falls to zero. - * - * @param event the event - */ -void afb_event_unref( - afb_event_t event); -``` - -### afb_event_addref - -```C -/** - * Increases the count of references to 'event' - * - * @param event the event - * - * @return the event - */ -afb_event_t *afb_event_addref( - afb_event_t event); -``` - -## Pushing functions - -### afb_event_broadcast - -```C -/** - * Broadcasts widely an event of 'event' with the data 'object'. - * 'object' can be NULL. - * - * For convenience, the function calls 'json_object_put' for 'object'. - * Thus, in the case where 'object' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param event the event to broadcast - * @param object the companion object to associate to the broadcasted event (can be NULL) - * - * @return 0 in case of success or -1 in case of error - */ -int afb_event_broadcast( - afb_event_t event, - struct json_object *object); -``` - -### afb_event_push - -```C -/** - * Pushes an event of 'event' with the data 'object' to its observers. - * 'object' can be NULL. - * - * For convenience, the function calls 'json_object_put' for 'object'. - * Thus, in the case where 'object' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param event the event to push - * @param object the companion object to associate to the pushed event (can be NULL) - * - * @Return - * * 1 if at least one client listen for the event - * * 0 if no more client listen for the event - * * -1 in case of error (the event can't be delivered) - */ -int afb_event_push( - afb_event_t event, - struct json_object *object); -``` - -vi. FUNCTIONS OF CLASS **afb_daemon** -============================ - -All the functions of the class **afb_daemon** use the default api. -This are internally aliased to the corresponding function of class afb_api_t. - -```C -/** - * Retrieves the common systemd's event loop of AFB - */ -struct sd_event *afb_daemon_get_event_loop(); - -/** - * Retrieves the common systemd's user/session d-bus of AFB - */ -struct sd_bus *afb_daemon_get_user_bus(); - -/** - * Retrieves the common systemd's system d-bus of AFB - */ -struct sd_bus *afb_daemon_get_system_bus(); - -/** - * Broadcasts widely the event of 'name' with the data 'object'. - * 'object' can be NULL. - * - * For convenience, the function calls 'json_object_put' for 'object'. - * Thus, in the case where 'object' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * Calling this function is only forbidden during preinit. - * - * Returns the count of clients that received the event. - */ -int afb_daemon_broadcast_event( - const char *name, - struct json_object *object); - -/** - * Creates an event of 'name' and returns it. - * - * Calling this function is only forbidden during preinit. - * - * See afb_event_is_valid to check if there is an error. - */ -afb_event_t afb_daemon_make_event( - const char *name); - -/** - * @deprecated use bindings version 3 - * - * Send a message described by 'fmt' and following parameters - * to the journal for the verbosity 'level'. - * - * 'file', 'line' and 'func' are indicators of position of the code in source files - * (see macros __FILE__, __LINE__ and __func__). - * - * 'level' is defined by syslog standard: - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - */ -void afb_daemon_verbose( - int level, - const char *file, - int line, - const char * func, - const char *fmt, - ...); - -/** - * @deprecated use bindings version 3 - * - * Get the root directory file descriptor. This file descriptor can - * be used with functions 'openat', 'fstatat', ... - * - * Returns the file descriptor or -1 in case of error. - */ -int afb_daemon_rootdir_get_fd(); - -/** - * Opens 'filename' within the root directory with 'flags' (see function openat) - * using the 'locale' definition (example: "jp,en-US") that can be NULL. - * - * Returns the file descriptor or -1 in case of error. - */ -int afb_daemon_rootdir_open_locale( - const char *filename, - int flags, - const char *locale); - -/** - * Queue the job defined by 'callback' and 'argument' for being executed asynchronously - * in this thread (later) or in an other thread. - * If 'group' is not NUL, the jobs queued with a same value (as the pointer value 'group') - * are executed in sequence in the order of there submission. - * If 'timeout' is not 0, it represent the maximum execution time for the job in seconds. - * At first, the job is called with 0 as signum and the given argument. - * The job is executed with the monitoring of its time and some signals like SIGSEGV and - * SIGFPE. When a such signal is catched, the job is terminated and reexecuted but with - * signum being the signal number (SIGALRM when timeout expired). - * - * Returns 0 in case of success or -1 in case of error. - */ -int afb_daemon_queue_job( - void (*callback)(int signum, void *arg), - void *argument, - void *group, - int timeout); - -/** - * Tells that it requires the API of "name" to exist - * and if 'initialized' is not null to be initialized. - * Calling this function is only allowed within init. - * - * Returns 0 in case of success or -1 in case of error. - */ -int afb_daemon_require_api( - const char *name, - int initialized); - -/** - * Create an aliased name 'as_name' for the api 'name'. - * Calling this function is only allowed within preinit. - * - * Returns 0 in case of success or -1 in case of error. - */ -int afb_daemon_add_alias(const char *name, const char *as_name); - -/** - * Creates a new api of name 'api' with brief 'info'. - * - * Returns 0 in case of success or -1 in case of error. - */ -int afb_daemon_new_api( - const char *api, - const char *info, - int noconcurrency, - int (*preinit)(void*, struct afb_api_x3 *), - void *closure); -``` - -vii. FUNCTIONS OF CLASS **afb_service** -============================== - -All the functions of the class **afb_service** use the default api. - -All these function are deprecated, try to use functions of class **afb_api** instead. - -## afb_service_call - -```C -/** - * @deprecated try to use @ref afb_api_call instead - * - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. - * The result of the call is delivered to the 'callback' function with the 'callback_closure'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * The 'callback' receives 5 arguments: - * 1. 'closure' the user defined closure pointer 'closure', - * 2. 'object' a JSON object returned (can be NULL) - * 3. 'error' a string not NULL in case of error but NULL on success - * 4. 'info' a string handling some info (can be NULL) - * 5. 'api' the api - * - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param callback The to call on completion - * @param closure The closure to pass to the callback - * - * - * @see afb_req_subcall - * @see afb_req_subcall_sync - * @see afb_api_call_sync - */ -void afb_service_call( - const char *api, - const char *verb, - struct json_object *args, - void (*callback)( - void *closure, - struct json_object *object, - const char *error, - const char * info, - afb_api_t api), - void *closure); -``` - -## afb_service_call_sync - -```C -/** - * @deprecated try to use @ref afb_api_call_sync instead - * - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. - * 'result' will receive the response. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param object Where to store the returned object - should call json_object_put on it - can be NULL - * @param error Where to store the copied returned error - should call free on it - can be NULL - * @param info Where to store the copied returned info - should call free on it - can be NULL - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see afb_req_subcall - * @see afb_req_subcall_sync - * @see afb_api_call - */ -int afb_service_call_sync( - const char *api, - const char *verb, - struct json_object *args, - struct json_object **object, - char **error, - char **info); -``` - -## afb_service_call_legacy - -```C -/** - * @deprecated try to use @ref afb_api_call instead - * - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' - * in the name of the binding. - * The result of the call is delivered to the 'callback' function with - * the 'callback_closure'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * The 'callback' receives 3 arguments: - * 1. 'closure' the user defined closure pointer 'closure', - * 2. 'status' a status being 0 on success or negative when an error occurred, - * 2. 'result' the resulting data as a JSON object. - * - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param callback The to call on completion - * @param closure The closure to pass to the callback - * - * @see also 'afb_api_call' - * @see also 'afb_api_call_sync' - * @see also 'afb_api_call_sync_legacy' - * @see also 'afb_req_subcall' - * @see also 'afb_req_subcall_sync' - */ -void afb_service_call_legacy( - const char *api, - const char *verb, - struct json_object *args, - void (*callback)( - void *closure, - int status, - struct json_object *result, - afb_api_t api), - void *closure); -``` - -## afb_service_call_sync_legacy - -```C -/** - * @deprecated try to use @ref afb_api_call_sync instead - * - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the - * name of the binding. 'result' will receive the response. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param result Where to store the result - should call json_object_put on it - - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see also 'afb_api_call' - * @see also 'afb_api_call_sync' - * @see also 'afb_api_call_legacy' - * @see also 'afb_req_subcall' - * @see also 'afb_req_subcall_sync' - */ -int afb_service_call_sync_legacy( - const char *api, - const char *verb, - struct json_object *args, - struct json_object **result); -``` \ No newline at end of file diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/4_Binder_events_guide.md b/docs/3_Developer_Guides/2_Application_Framework_Binder/4_Binder_events_guide.md deleted file mode 100644 index 57175a6..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/4_Binder_events_guide.md +++ /dev/null @@ -1,291 +0,0 @@ ---- -title: Binder events guide ---- - -Signaling agents are services that send events to any clients that -are subscribed to receive it. -The sent events carry any data. - -To have a good understanding of how to: - -- 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: - -![scenario of using events](images/signaling-basis.svg) - -This figure shows the main role of the signaling framework for the events -propagation. - -For people not familiar with the framework, a signaling agent and -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 : - -1. Create resources for generating the data. -2. Deliver 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 -2. 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. - -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, -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 -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 -events. - -Events are created using the ***afb\_api\_make\_event*** function -that takes the api that creates the event and the name of the event. -Example: - -```C - event = afb_api_make_event(api, 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 -that takes the current request object and event and associates them -together. -Example: - -```C - 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 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. -- 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. - -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. - -The framework only uses the event (not its name) for: - -- 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. - -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. -Example: - -```C - 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. - -#### 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 -automatically prefixed by the framework, using the API prefix of the -binding. - -Thus, if a signaling agent of API prefix ***api*** creates an event -of name ***event*** and pushes data to that event, the subscribers -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 -provide a way to integrates to the main loop of this library using -afb\_api\_get\_event\_loop. -Example: - -```C - sdev = afb_api_get_event_loop(api); - 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\_api\_get\_system\_bus*** or -***afb\_api\_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: - -```C - rc = afb_event_push(event, JSON); - if (rc == 0) { - stop_generating(event); - afb_event_unref(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 tells that it doesn't use it anymore by calling -**afb\_event\_unref**. - -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 -format, structured data can be sent in a flexible way. - -The good design is to allow as much as possible the client to describe -what is needed with the goal to optimize the processing to the -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: - -- 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\_api\_broadcast\_event*** -- ***afb\_event\_broadcast*** - -Example 1: - -```C -afb_api_broadcast_event(api, name, json); -``` - -Example 2: - -```C -event = afb_api_make_event(api, name); -. . . . -afb_event_broadcast(event, json); -``` - -As for other events, the name of events broadcasted using -***afb\_api\_broadcast\_event*** are automatically prefixed by -the framework with API prefix. - -## Reference of functions - -See the [references for functions of class afb_event](3_Binder_References.md#v-FUNCTIONS-OF-CLASS-afb_event) - -### Function onevent (field of afbBindingExport) - -Binding can designate an event handling function using the field **onevent** -of the structure **afb_binding_t**. - -This function is called when an event is broadcasted or when an event that the -api subscribed to (through call or subcall mechanism) is pushed. -That behavior allows 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.). - -### Event handlers - -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. \ No newline at end of file diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/5_Binder_Application_writing_guide.md b/docs/3_Developer_Guides/2_Application_Framework_Binder/5_Binder_Application_writing_guide.md deleted file mode 100644 index 4886e5d..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/5_Binder_Application_writing_guide.md +++ /dev/null @@ -1,319 +0,0 @@ ---- -title: Binder Application writing guide ---- - -### Writing an HTML5 application - -Developers of HTML5 applications (client side) can easily create -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 -and can be accessed though either HTTP or Websockets. - -In a near future, JSON-RPC protocol should be added to complete the current -x-afb-json1 protocol. - -Two examples of HTML5 applications are given: - -- [afb-client](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-demo.git;a=tree;f=afb-client) a simple "hello world" application template - -- [afm-client](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-demo.git;a=tree;f=afm-client) a simple "Home screen" application template - -### Writing a Qt application - -Writing Qt applications is also supported. -Qt offers standard API to send request through HTTP or WebSockets. - -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 - -### Writing a "C" application - -C applications can use afb-daemon binder through a websocket connection. - -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 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 may be reviewed in the future to support secure sockets -and get rid of libsystemd dependency. - -### 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 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 -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.” - -The examples **token-websock.qml** and **afb-client** are demonstrating -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 -as they may typically have to keep each client's data separated. - -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 -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**". - -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. - -The token must be included in URI request on HTTP or during websockets -connection using parameter **token** or **x-afb-token**. - -To ensure security, tokens must be refreshed periodically. - -### Example of session management - -In following examples, we suppose that **afb-daemon** is launched with something -equivalent to: - -```bash -afb-daemon --port=1234 --token=123456 [...] -``` - -making the expectation that **AuthLogin** binding is requested as default. - -#### Using curl - -First, connects with the initial token, 123456: - -```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: - -```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: - -```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: - -```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: - -```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** - -Here is an example of exchange using **afb-client-demo**: - -```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: - -```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**: - -```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 - -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 of replies - -This is a template of replies: - -```json -{ - "jtype": "afb-reply", - "request": { - "status": "success", - "info": "informationnal text", - "token": "e83b36f8-d945-463d-b983-5d8ed73ba52", - "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1", - "reqid": "application-generated-id-23456" - }, - "response": ....any response object.... -} -``` - -#### Field jtype of replies - -The field **jtype** must have a value of type string equal to **"afb-reply"**. - -#### 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**. - -##### 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 - -**info** is of type string and represent optional information added to the reply. - -##### Subfield request.token - -**token** is of type string. It is sent either at session creation -or when the token is refreshed. - -##### Subfield request.uuid - -**uuid** is of type string. It is sent at session creation. - -##### 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 of replies - -This field response optionally contains an object returned when request -succeeded. - -### Format of events - -Events are javascript object serialized as JSON. - -This object contains at least 2 mandatory fields of name **jtype** and **event** -and one optional field of name **data**. - -#### Template of event - -Here is a template of event: - -```json -{ - "jtype": "afb-event", - "event": "sample_api_name/sample_event_name", - "data": ...any event data... -} -``` - -#### Field jtype of event - -The field **jtype** must have a value of type string equal to **"afb-event"**. - -#### Field event of event - -The field **event** carries the event's name. - -The name of the event is made of two parts separated by a slash: -the name of the name of the API that generated the event -and the name of event within the API. - -#### Field data of event - -This field data if present holds the data carried by the event. \ No newline at end of file diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/7_Document_revisions.md b/docs/3_Developer_Guides/2_Application_Framework_Binder/7_Document_revisions.md deleted file mode 100644 index 06242ce..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/7_Document_revisions.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Document revisions ---- - -Document revisions - -| Date | Version | Designation  | Author | -|--------------|:----------:|----------------------------------------------|-------------------------------------------------------| -| 23 May 2016 | 0.9 | Initial release | J. Bollo [ IoT.bzh ]
M. Bachmann [ IoT.bzh ] | -| 30 May 2016 | 1.0 | Master document edition, final review | S. Desneux [ IoT.bzh ]
F. Ar Foll [ IoT.bzh ] | -| 21 Sept 2016 | 2.0 | Updated with new sections (events,widgets) | J. Bollo [ IoT.bzh ]
S. Desneux [ IoT.bzh ] | -| 12 Dec 2016 | 2.1 | Updated for CC Release | S. Desneux [ IoT.bzh ] | -| 14 Dec 2016 | 3.0 | Minor fixes, alignment with CC version | S. Desneux [ IoT.bzh ] | -| 20 Mar 2017 | 3.1 | Systemd integration | J. Bollo [ IoT.bzh ]
S. Desneux [ IoT.bzh ] | -| 21 Jun 2017 | 4.0 | Update for AGL DD | J. Bollo [ IoT.bzh ]
S. Desneux [ IoT.bzh ] | -| 21 Sep 2017 | 4.99-EERC1 | Update for AGL EE-RC1 | J. Bollo [ IoT.bzh ]
S. Desneux [ IoT.bzh ] | -| 14 Jun 2018 | 5.99-FFRC1 | Update for AGL FF-RC1 | J. Bollo [ IoT.bzh ] | diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/1_Migration_to_bindings_v3.md b/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/1_Migration_to_bindings_v3.md deleted file mode 100644 index bba5354..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/1_Migration_to_bindings_v3.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: Migration to bindings v3 ---- - -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 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 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 do not exist anymore. If needed you can refer -to the old [guide to migrate bindings from v1 to v2](./6_LEGACY_Migration_from_v1_to_v2.md). - - -Differences between version 2 and version 3 -------------------------------------------- - -** *In v3 all is api.* ** - -The version 3 introduces the concept of "API" that gather what was called before -the daemon and the service. This is the new concept that predates the 2 others. - -The concept of API is intended to allow the definition of multiple APIs -by a same "binding" (a dynamically loaded library). - -Because there is potentially several "API", the functions that were without -context in bindings version 2 need now to tell what API is consumer. - -To be compatible with version 2, bindings v3 still have a default hidden -context: the default API named **afbBindingV3root**. - -To summarize, the functions of class **daemon** and **service** use the default -hidden API. - -It is encouraged to avoid use of functions of class **daemon** and **service**. -You should replace these implicit calls to explicit **api** calls that -reference **afbBindingV3root**. - -Same thing for the logging macros: **AFB_ERROR**, **AFB_WARNING**, -**AFB_NOTICE**, **AFB_INFO**, **AFB_DEBUG** that becomes respectively -**AFB_API_ERROR**, **AFB_API_WARNING**, **AFB_API_NOTICE**, **AFB_API_INFO**, -**AFB_API_DEBUG**. - -Example of 2 equivalent writes: - -```C - AFB_NOTICE("send stress event"); - afb_daemon_broadcast_event(stressed_event, NULL); -``` - -or - -```C - AFB_API_NOTICE(afbBindingV3root, "send stress event"); - afb_api_broadcast_event(afbBindingV3root, stressed_event, NULL); -``` - -**The reply mechanism predates success and fail. Subcall has more power.** - -Task list for the migration ---------------------------- - -This task list is: - -1. Use the automatic migration procedure described below -2. Adapt the functions **preinit**, **init** and **onevent** -3. Consider use of the new reply -4. Consider use of the new (sub)call -5. Consider use of event handlers - -The remaining chapters explain these task with more details. - -Automatic migration! --------------------- - -A tiny **sed** script is intended to perform a first pass on the code that -you want to upgrade. It can be done using **curl** and applied using **sed** -as below. - -```bash -BASE=https://git.automotivelinux.org/src/app-framework-binder/plain -SED=migration-to-binding-v3.sed -curl -o $SED $BASE/docs/$SED -sed -i -f $SED file1 file2 file3... -``` - -You can also follow -[this link](https://git.automotivelinux.org/src/app-framework-binder/plain/docs/migration-to-binding-v3.sed) -and save the file. - -This automatic action does most of the boring job but not all the job. -The remaining of this guide explains the missing part. - -Adapt the functions preinit, init and onevent ----------------------------------------------- - -The signature of the functions **preinit**, **init** and **onevent** changed -to include the target api. - -The functions of the v2: - -```C -int (*preinit)(); -int (*init)(); -void (*onevent)(const char *event, struct json_object *object); -``` - -Gain a new first argument of type **afb_api_t** as below: - -```C -int (*preinit)(afb_api_t api); -int (*init)(afb_api_t api); -void (*onevent)(afb_api_t api, const char *event, struct json_object *object); -``` - -For the migration, it is enough to just add the new argument without -using it. - -Consider use of the new reply ------------------------------ - -The v3 allows error reply with JSON object. To achieve it, an unified -reply function's family is introduced: - -```C -void afb_req_reply(afb_req_t req, json_object *obj, const char *error, const char *info); -void afb_req_reply_v(afb_req_t req, json_object *obj, const char *error, const char *info, va_list args); -void afb_req_reply_f(afb_req_t req, json_object *obj, const char *error, const char *info, ...); -``` - -The functions **success** and **fail** are still supported. -These functions are now implemented as the following macros: - - -```C -#define afb_req_success(r,o,i) afb_req_reply(r,o,NULL,i) -#define afb_req_success_f(r,o,...) afb_req_reply_f(r,o,NULL,__VA_ARGS__) -#define afb_req_success_v(r,o,f,v) afb_req_reply_v(r,o,NULL,f,v) -#define afb_req_fail(r,e,i) afb_req_reply(r,NULL,e,i) -#define afb_req_fail_f(r,e,...) afb_req_reply_f(r,NULL,e,__VA_ARGS__) -#define afb_req_fail_v(r,e,f,v) afb_req_reply_v(r,NULL,e,f,v) -``` - -This is a decision of the developer to switch to the new family -**afb_req_reply** or to keep the good old functions **afb_req_fail** -adn **afb_req_success**. - -Consider use of the new (sub)call ---------------------------------- - -The new call and subcall (the functions **afb_api_call**, **afb_api_call_sync**, -**afb_req_subcall** and **afb_req_subcall_sync**) functions are redesigned -to better fit the new reply behaviour. In most case the developer will benefit -of the new behavior that directly gives result and error without enforcing -to parse the JSON object result. - -The subcall functions are also fully redesigned to allow precise handling -of the context and event subscriptions. The new design allows you to specify: - - - whether the subcall is made in the session of the caller or in the session - of the service - - whether the credentials to use are those of the caller or those of the - service - - whether the caller or the service or both or none will receive the - eventually events during the subcall. - -See [calls](../3_Binder_References.md#afb_api_call) and -[subcalls](../3_Binder_References.md#subcall-functions). - -The table below list the changes to apply: - -| Name in Version 2 | New name of Version 3 -|:----------------------:|:----------------------------------------------------: -| afb_req_subcall | afb_req_subcall_legacy -| afb_req_subcall_sync | afb_req_subcall_sync_legacy -| afb_service_call | afb_service_call_legacy -| afb_service_call_sync | afb_service_call_sync_legacy -| afb_req_subcall_req | afb_req_subcall_req (same but obsolete) - - -Consider use of event handlers ------------------------------- - -Binding V3 brings new ways of handling event in services. You can register -functions that will handle specific events and that accept closure arguments. - -See [**afb_api_event_handler_add** and **afb_api_event_handler_del**](../3_Binder_References.md#event-functions) \ No newline at end of file diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/2_WebSocket_protocol_x-afb-ws-json1.md b/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/2_WebSocket_protocol_x-afb-ws-json1.md deleted file mode 100644 index 7ebf22a..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/2_WebSocket_protocol_x-afb-ws-json1.md +++ /dev/null @@ -1,308 +0,0 @@ ---- -title: WebSocket protocol x-afb-ws-json1 ---- - -The WebSocket protocol *x-afb-ws-json1* is used to communicate between -an application and a binder. It allows access to all registered apis -of the binder. - -This protocol is inspired from the protocol **OCPP - SRPC** as described for -example here: -[OCPP transport specification - SRPC over WebSocket](http://www.gir.fr/ocppjs/ocpp_srpc_spec.shtml). - -The registration to the IANA is still to be done, see: -[WebSocket Protocol Registries](https://www.iana.org/assignments/websocket/websocket.xml) - -This document gives a short description of the protocol *x-afb-ws-json1*. -A more formal description has to be done. - -## Architecture - -The protocol is intended to be symmetric. It allows: - -- to CALL a remote procedure that returns a result -- to push and receive EVENT - -## Messages - -Valid messages are made of *text* frames that are all valid JSON. - -Valid messages are: - -Calls: - -```txt -[ 2, ID, PROCN, ARGS ] -[ 2, ID, PROCN, ARGS, TOKEN ] -``` - -Replies (3: OK, 4: ERROR): - -```txt -[ 3, ID, RESP ] -[ 4, ID, RESP ] -``` - -Events: - -```txt -[ 5, EVTN, OBJ ] -``` - -Where: - -| Field | Type | Description -|-------|--------|------------------ -| ID | string | A string that identifies the call. A reply to that call use the ID of the CALL. -| PROCN | string | The procedure name to call of the form "api/verb" -| ARGS | any | Any argument to pass to the call (see afb_req_json that returns it) -| RESP | any | The response to the call -| TOKEN | string | The authorisation token -| EVTN | string | Name of the event in the form "api/event" -| OBJ | any | The companion object of the event - -Below, an example of exchange: - -```txt -C->S: [2,"156","hello/ping",null] -S->C: [3,"156",{"response":"Some String","jtype":"afb-reply","request":{"status":"success","info":"Ping Binder Daemon tag=pingSample count=1 query=\"null\"","uuid":"ec30120c-6997-4529-9d63-c0de0cce56c0"}}] -``` - -## History - -### 14 November 2019 - -Removal of token returning. The replies - -```txt -[ 3, ID, RESP, TOKEN ] -[ 4, ID, RESP, TOKEN ] -``` - -are removed from the specification. - -## Future - -Here are the planned extensions: - -- add binary messages with cbor data -- add calls with unstructured replies - -This could be implemented by extending the current protocol or by -allowing the binder to accept either protocol including the new ones. - -## Javascript implementation - -The file **AFB.js** is a javascript implementation of the protocol. - -Here is that code: - -```javascript -/* - * Copyright (C) 2017-2019 "IoT.bzh" - * Author: José Bollo - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -AFB = function(base, initialtoken){ - -if (typeof base != "object") - base = { base: base, token: initialtoken }; - -var initial = { - base: base.base || "api", - token: base.token || initialtoken || "HELLO", - host: base.host || window.location.host, - url: base.url || undefined -}; - -var urlws = initial.url || "ws://"+initial.host+"/"+initial.base; - -/*********************************************/ -/**** ****/ -/**** AFB_context ****/ -/**** ****/ -/*********************************************/ -var AFB_context; -{ - var UUID = undefined; - var TOKEN = initial.token; - - var context = function(token, uuid) { - this.token = token; - this.uuid = uuid; - } - - context.prototype = { - get token() {return TOKEN;}, - set token(tok) {if(tok) TOKEN=tok;}, - get uuid() {return UUID;}, - set uuid(id) {if(id) UUID=id;} - }; - - AFB_context = new context(); -} -/*********************************************/ -/**** ****/ -/**** AFB_websocket ****/ -/**** ****/ -/*********************************************/ -var AFB_websocket; -{ - var CALL = 2; - var RETOK = 3; - var RETERR = 4; - var EVENT = 5; - - var PROTO1 = "x-afb-ws-json1"; - - AFB_websocket = function(on_open, on_abort) { - var u = urlws; - if (AFB_context.token) { - u = u + '?x-afb-token=' + AFB_context.token; - if (AFB_context.uuid) - u = u + '&x-afb-uuid=' + AFB_context.uuid; - } - this.ws = new WebSocket(u, [ PROTO1 ]); - this.url = u; - this.pendings = {}; - this.awaitens = {}; - this.counter = 0; - this.ws.onopen = onopen.bind(this); - this.ws.onerror = onerror.bind(this); - this.ws.onclose = onclose.bind(this); - this.ws.onmessage = onmessage.bind(this); - this.onopen = on_open; - this.onabort = on_abort; - } - - function onerror(event) { - var f = this.onabort; - if (f) { - delete this.onopen; - delete this.onabort; - f && f(this); - } - this.onerror && this.onerror(this); - } - - function onopen(event) { - var f = this.onopen; - delete this.onopen; - delete this.onabort; - f && f(this); - } - - function onclose(event) { - for (var id in this.pendings) { - try { this.pendings[id][1](); } catch (x) {/*TODO?*/} - } - this.pendings = {}; - this.onclose && this.onclose(); - } - - function fire(awaitens, name, data) { - var a = awaitens[name]; - if (a) - a.forEach(function(handler){handler(data);}); - var i = name.indexOf("/"); - if (i >= 0) { - a = awaitens[name.substring(0,i)]; - if (a) - a.forEach(function(handler){handler(data);}); - } - a = awaitens["*"]; - if (a) - a.forEach(function(handler){handler(data);}); - } - - function reply(pendings, id, ans, offset) { - if (id in pendings) { - var p = pendings[id]; - delete pendings[id]; - try { p[offset](ans); } catch (x) {/*TODO?*/} - } - } - - function onmessage(event) { - var obj = JSON.parse(event.data); - var code = obj[0]; - var id = obj[1]; - var ans = obj[2]; - AFB_context.token = obj[3]; - switch (code) { - case RETOK: - reply(this.pendings, id, ans, 0); - break; - case RETERR: - reply(this.pendings, id, ans, 1); - break; - case EVENT: - default: - fire(this.awaitens, id, ans); - break; - } - } - - function close() { - this.ws.close(); - this.ws.onopen = - this.ws.onerror = - this.ws.onclose = - this.ws.onmessage = - this.onopen = - this.onabort = function(){}; - } - - function call(method, request, callid) { - return new Promise((function(resolve, reject){ - var id, arr; - if (callid) { - id = String(callid); - if (id in this.pendings) - throw new Error("pending callid("+id+") exists"); - } else { - do { - id = String(this.counter = 4095 & (this.counter + 1)); - } while (id in this.pendings); - } - this.pendings[id] = [ resolve, reject ]; - arr = [CALL, id, method, request ]; - if (AFB_context.token) arr.push(AFB_context.token); - this.ws.send(JSON.stringify(arr)); - }).bind(this)); - } - - function onevent(name, handler) { - var id = name; - var list = this.awaitens[id] || (this.awaitens[id] = []); - list.push(handler); - } - - AFB_websocket.prototype = { - close: close, - call: call, - onevent: onevent - }; -} -/*********************************************/ -/**** ****/ -/**** ****/ -/**** ****/ -/*********************************************/ -return { - context: AFB_context, - ws: AFB_websocket -}; -}; -``` diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/3_Installing_the_binder_on_a_desktop.md b/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/3_Installing_the_binder_on_a_desktop.md deleted file mode 100644 index 8874bde..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/3_Installing_the_binder_on_a_desktop.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Installing the binder on a desktop ---- - -Packages of the ***binder*** (afb-daemon)exist -for common desktop linux distributions. - -- Fedora -- Ubuntu -- Debian -- Suse - -Installing the development package of the ***binder*** -allows to write ***bindings*** that runs on the desktop -computer of the developer. - -It is very convenient to quickly write and debug a binding. - -## Retrieving compiling option with pkg-config - -The ***binder*** afb-daemon provides a configuration -file for **pkg-config**. -Typing the command - -```bash -pkg-config --cflags afb-daemon -``` - -Print flags use for compilation: - -```bash -$ pkg-config --cflags afb-daemon --I/opt/local/include -I/usr/include/json-c -``` - -For linking, you should use - -```bash -$ pkg-config --libs afb-daemon --ljson-c -``` - -It automatically includes the dependency to json-c. -This is activated through **Requires** keyword in pkg-config. diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/4_Options_of_afb-daemon.md b/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/4_Options_of_afb-daemon.md deleted file mode 100644 index 0b58eec..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/4_Options_of_afb-daemon.md +++ /dev/null @@ -1,355 +0,0 @@ ---- -title: Options of afb-daemon ---- - -The launch options for binder **afb-daemon** are: - -``` - -v, --verbose Verbose Mode, repeat to increase verbosity - -c, --color Colorize the ouput - -q, --quiet Quiet Mode, repeat to decrease verbosity - -l, --log=xxxx Tune log level - --foreground Get all in foreground mode - --background Get all in background mode - -D, --daemon Get all in background mode - -n, --name=xxxx Set the visible name - -p, --port=xxxx HTTP listening TCP port [default 1234] - --roothttp=xxxx HTTP Root Directory [default no root http (files not served but apis still available)] - --rootbase=xxxx Angular Base Root URL [default /opa] - --rootapi=xxxx HTML Root API URL [default /api] - --alias=xxxx Multiple url map outside of rootdir [eg: --alias=/icons:/usr/share/icons] - --apitimeout=xxxx Binding API timeout in seconds [default 20] - --cntxtimeout=xxxx Client Session Context Timeout [default 32000000] - --cache-eol=xxxx Client cache end of live [default 100000] - -w, --workdir=xxxx Set the working directory [default: $PWD or current working directory] - -u, --uploaddir=xxxx Directory for uploading files [default: workdir] relative to workdir - --rootdir=xxxx Root Directory of the application [default: workdir] relative to workdir - --ldpaths=xxxx Load bindings from dir1:dir2:... [default: path of afb-dbus-binding.so] - -b, --binding=xxxx Load the binding of path - --weak-ldpaths=xxxx Same as --ldpaths but ignore errors - --no-ldpaths Discard default ldpaths loading - -t, --token=xxxx Initial Secret [default=random, use --token= to allow any token] - -r, --random-token Enforce a random token - -V, --version Display version and copyright - -h, --help Display this help - --ws-client=xxxx Bind to an afb service through websocket - --ws-server=xxxx Provide an afb service through websockets - -A, --auto-api=xxxx Automatic load of api of the given directory - --session-max=xxxx Max count of session simultaneously [default 200] - --tracereq=xxxx Log the requests: no, common, extra, all - --traceevt=xxxx Log the events: no, common, extra, all - --traceses=xxxx Log the sessions: no, all - --traceapi=xxxx Log the apis: no, common, api, event, all - --traceglob=xxxx Log the globals: none, all - --traceditf=xxxx Log the daemons: no, common, all - --tracesvc=xxxx Log the services: no, all - --call=xxxx call at start, format of val: API/VERB:json-args - --no-httpd Forbid HTTP service - -e, --exec Execute the remaining arguments - -M, --monitoring Enable HTTP monitoring at /monitoring/ - -C, --config=xxxx Load options from the given config file - -Z, --dump-config Dump the config to stdout and exit - -s, --set=xxxx Set parameters ([API]/[KEY]:JSON or {"API":{"KEY":JSON}} - -o, --output=xxxx Redirect stdout and stderr to output file (when --daemon) - --trap-faults=xxxx Trap faults: on, off, yes, no, true, false, 1, 0 (default: true) -``` - -## help - -Prints help with available options - -## version - -Display version and copyright - -## verbose - -Increases the verbosity, can be repeated - -## color - -Add basic colorization to the ouput. - -## quiet - -Decreases the verbosity, can be repeated - -## log=xxxx - -Tune the log level mask. The levels are: - - - error - - warning - - notice - - info - - debug - -The level can be set using + or -. - -| Examples | descritpion -|-----------------|------------------- -| error,warning | selects only the levels error and warning -| +debug | adds level debug to the current verbosity -| -warning | remove the level warning from the current verbosity -| +warning-debug,info | Adds error and remove errors and warnings - -## port=xxxx - -HTTP listening TCP port [default 1234] - -## workdir=xxxx - -Directory where the daemon must run [default: $PWD if defined -or the current working directory] - -## uploaddir=xxxx - -Directory where uploaded files are temporarily stored [default: workdir] - -## rootdir=xxxx - -Root directory of the application to serve [default: workdir] - -## roothttp=xxxx - -Directory of HTTP served files. If not set, files are not served -but apis are still accessible. - -## rootbase=xxxx - -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 - -## rootapi=xxxx - -HTML Root API URL [default /api] - -The bindings are available within that url. - -## 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. - -Example: --alias=/icons:/usr/share/icons maps the -content of /usr/share/icons within the subpath /icons. - -This option can be repeated. - -## apitimeout=xxxx - -binding API timeout in seconds [default 20] - -Defines how many seconds maximum a method is allowed to run. -0 means no limit. - -## cntxtimeout=xxxx - -Client Session Timeout in seconds [default 32000000 that is 1 year] - -## cache-eol=xxxx - -Client cache end of live [default 100000 that is 27,7 hours] - -## session-max=xxxx - -Maximum count of simultaneous sessions [default 200] - -## ldpaths=xxxx - -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. - -The bindings are the files terminated by '.so' (the extension -so denotes shared object) that contain the public entry symbol. - -## weak-ldpaths=xxxx - -Same as --ldpaths but instead of stopping on error, ignore errors and continue. - -## binding=xxxx - -Load the binding of given path. - -## token=xxxx - -Initial Secret token to authenticate. - -If not set, no client can authenticate. - -If set to the empty string, then any initial token is accepted. - -## random-token - -Generate a random starting token. See option --exec. - -## ws-client=xxxx - -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". - -## ws-server=xxxx - -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". - -## foreground - -Get all in foreground mode (default) - -## daemon - -Get all in background mode - -## no-httpd - -Forbids HTTP serve - -## 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 @. - -## tracereq=xxxx - -Trace the processing of requests in the log file. - -Valid values are 'no' (default), 'common', 'extra' or 'all'. - -## traceapi=xxxx - -Trace the accesses to functions of class api. - -Valid values are 'no' (default), 'common', 'api', 'event' or 'all'. - -## traceevt=xxxx - -Trace the accesses to functions of class event. - -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. - -Example: --call 'monitor/set:{"verbosity":{"api":"debug"}}' - -## monitoring - -Enable HTTP monitoring at /monitoring/ - -## name=xxxx - -Set the visible name - -## auto-api=xxxx - -Automatic activation of api of the given directory when the api is missing. - -## config=xxxx - -Load options from the given config file - -This can be used instead of arguments on the command line. - -Example: - - afb-daemon \ - --no-ldpaths \ - --binding /home/15646/bindings/binding45.so \ - --binding /home/15646/bindings/binding3.so \ - --tracereq common \ - --port 5555 \ - --token SPYER \ - --set api45/key:54027a5e3c6cb2ca5ddb97679ce32f185b067b0a557d16a8333758910bc25a72 \ - --exec /home/15646/bin/test654 @p @t - -is equivalent to: - - afb-daemon --config /home/15646/config1 - -when the file **/home/15646/config1** is: - - { - "no-ldpaths": true, - "binding": [ - "\/home\/15646\/bindings\/binding45.so", - "\/home\/15646\/bindings\/binding3.so" - ], - "tracereq": "common", - "port": 5555, - "token": "SPYER", - "set" : { - "api45": { - "key": "54027a5e3c6cb2ca5ddb97679ce32f185b067b0a557d16a8333758910bc25a72" - } - }, - "exec": [ - "\/home\/15646\/bin\/test654", - "@p", - "@t" - ] - } - -The options are the keys of the config object. - -See option --dump-config - -## dump-config - -Output a JSON representation of the configuration resulting from -environment and options. - -## output=xxxx - -Redirect stdout and stderr to output file - -## set=xxxx - -Set values that can be retrieved by bindings. - -The set value can have different formats. - -The most generic format is **{"API1":{"KEY1":VALUE,"KEY2":VALUE2,...},"API2":...}** - -This example set 2 keys for the api *chook*: - - afb-daemon -Z --set '{"chook":{"account":"urn:chook:b2ca5ddb97679","delay":500}}' - { - "set": { - "chook": { - "account": "urn:chook:b2ca5ddb97679", - "delay": 500 - } - } - } - -An other format is: **[API]/[KEY]:VALUE**. -When API is omitted, it take the value " * ". -When KEY is ommitted, it take the value of " * ". - -The settings for the API \* are globals and apply to all bindings. - -The settings for the KEY \* are mixing the value for the API. - -The following examples are all setting the same values: - - afb-daemon --set '{"chook":{"account":"urn:chook:b2ca5ddb97679","delay":500}}' - afb-daemon --set 'chook/*:{"account":"urn:chook:b2ca5ddb97679","delay":500}' - afb-daemon --set 'chook/:{"account":"urn:chook:b2ca5ddb97679","delay":500}' - afb-daemon --set 'chook/account:"urn:chook:b2ca5ddb97679"' --set chook/delay:500 \ No newline at end of file diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/5_Debugging_binder_and_bindings.md b/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/5_Debugging_binder_and_bindings.md deleted file mode 100644 index dbb9bdd..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/5_Debugging_binder_and_bindings.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Debugging binder and bindings ---- - -When compiled with the symbol AGL_DEVEL defined, the ***binder*** -understands the 2 configuration variables: - - - AFB_DEBUG_BREAK: to emit interrupts - - AFB_DEBUG_WAIT: to wait interrupts - -To use these variables, assign it the list of break or wait points -to reach. - -Example: - -```bash -$ AFB_DEBUG_BREAK=main-entry AFB_DEBUG_WAIT=start-load,start-exec afb-daemon .... -``` - -This tells to ***afb-daemon*** to break at the point **main-entry** and to -wait at the points **start-load** and **start-exec**. - -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 occurrence: - -- main-entry: before decode arguments -- main-args: before daemon setup -- main-start: before starting jobs -- start-entry: before initialisation of sessions and hooks -- start-load: before load and pre-init of bindings -- start-start: before init of bindings -- start-http: before start of http server -- start-call: before execution of requests of the command line (option --call) -- start-exec: before execution of child preocees - -Note also that a call to 'personality' is inserted just after -the point start-start. \ No newline at end of file diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/6_LEGACY_Migration_from_v1_to_v2.md b/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/6_LEGACY_Migration_from_v1_to_v2.md deleted file mode 100644 index 6004aec..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/6_LEGACY_Migration_from_v1_to_v2.md +++ /dev/null @@ -1,656 +0,0 @@ ---- -title: LEGACY Migration from v1 to v2 ---- - -> LEGACY!!! IT IS NOT EXPECTED THAT YOU STILL NEED THIS GUIDE. -> -> THIS GUIDE WILL BE REMOVED IN A NEAR FUTURE - - -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 - -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. - -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 - -This guide covers the migration of bindings from version 1 to version 2. - -It also explains some of the rationale taken when migrating from version 1 to version 2. - -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. - -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. -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 - -For these functions, the first parameter is now implicit. - -Let takes an example. -For ***binding*** v1 you had to write: - -```C - afb_daemon_broadcast_event(afbitf->daemon, reason, description); -``` - -For ***binding*** v2, you simply write: - -```C - afb_daemon_broadcast_event(reason, description); -``` - -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. -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. - -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 - -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. -This is done as below. - -```C -#define AFB_BINDING_VERSION 2 -#include -``` - -After that you will get many errors when compiling. - -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: - -```C -struct afb_verb_desc_v1 -{ - const char *name; /* name of the verb */ - enum afb_session_flags_v1 session; /* authorization and session requirements of the verb */ - void (*callback)(struct afb_req req); /* callback function implementing the verb */ - const char *info; /* textual description of the verb */ -}; -``` - -In version 2 it becomes: - -```C -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 */ - uint32_t session; /* authorization and session requirements of the verb */ -}; - -``` - -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 - -Example: - -```C - { .name= "new", .session= AFB_SESSION_NONE, .callback= new, .info= "Starts a new game" } -``` - -Becomes - -```C - { .verb = "new", .session = AFB_SESSION_NONE, .callback = new, .auth = NULL } -``` - -The field **auth** can be set to a value describing the requested -authorization. - -The main describing structure also changed. - -In version 1 it was: - -```C -struct afb_binding_desc_v1 -{ - const char *info; /* textual information about the binding */ - const char *prefix; /* required prefix name for the binding */ - const struct afb_verb_desc_v1 *verbs; /* array of descriptions of verbs terminated by a NULL name */ -}; -``` - -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 */ - 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 */ -}; -``` - -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. - -Example: - -```C -static const struct afb_binding plugin_desc = { - .type = AFB_BINDING_VERSION_1, - .v1 = { - .info = "Minimal Hello World Sample", - .prefix = "hello", - .verbs = verbs - } -``` - -Becomes: - -```C -const struct afb_binding_v2 afbBindingV2 = { - .api = "hello", - .specification = NULL, - .verbs = verbs, - .preinit = preinit, - .init = init -}; -``` - -The **binder** now relies only on the exported names -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** - -These function should not be exported any more and there definition changed. - -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***. - -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. - -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**. -So the variable that ***bindings*** version used to store the ***binder*** interface -and the service interface are no more needed and can be removed. - -Example: - -```C -const struct afb_binding_interface *interface; -struct afb_service service; - -static const struct afb_binding plugin_desc = { - .type = AFB_BINDING_VERSION_1, - .v1 = { - .info = "Minimal Hello World Sample", - .prefix = "hello", - .verbs = verbs - } -} - -const struct afb_binding *afbBindingV1Register (const struct afb_binding_interface *itf) -{ - interface = itf; - NOTICE(interface, "binding register"); - return &plugin_desc; -} - -int afbBindingV1ServiceInit(struct afb_service svc) -{ - service = svc; - NOTICE(interface, "binding init"); - return 0; -} - -void afbBindingV1ServiceEvent(const char *event, struct json_object *object) -{ - NOTICE(interface, "onevent %s", event); -} -``` - -Becomes: - -```C -static int preinit() -{ - AFB_NOTICE("binding preinit (was register)"); - return 0; -} - -static int init() -{ - AFB_NOTICE("binding init"); - return 0; -} - -static void onevent(const char *event, struct json_object *object) -{ - AFB_NOTICE("onevent %s", event); -} - -const struct afb_binding_v2 afbBindingV2 = { - .api = "hello", - .specification = NULL, - .verbs = verbs, - .preinit = preinit, - .init = init, - .onevent = onevent -}; -``` - -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**. -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; - - interface = itf; - - 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 - -For these functions, the first parameter is now implicit. - -Example: - -```C - afb_daemon_broadcast_event(afbitf->daemon, reason, description); -``` - -Becomes: - -```C - 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. - -Example: - -```C - NOTICE(interface, "hello plugin comes to live"); -``` - -Become: - -```C - NOTICE("hello plugin comes to live"); -``` - -or, better: - -```C - 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** - -before to include **afb/afb-binding.h**. - -```C -#define AFB_BINDING_PRAGMA_NO_VERBOSE_UNPREFIX -#define AFB_BINDING_VERSION 2 -#include -``` - -Consider where to emit logs for 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** - -We encourage the use of these new logging facilities everywhere it makes sense. - -Example: - -```C - INFO(afbitf, "method 'new' called for boardid %d", board->id); -``` - -Might become: - -```C - AFB_REQ_INFO(req, "method 'new' called for boardid %d", board->id); -``` - -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. - -For ***bindings*** version, the signature of the functions were: - -```C -struct afb_req *afb_req_store(struct afb_req req); -struct afb_req afb_req_unstore(struct afb_req *req); -``` - -For version 2 it becomes - -```C -struct afb_stored_req *afb_req_store(struct afb_req req); -struct afb_req afb_req_unstore(struct afb_stored_req *sreq); -``` - -Where the structure ```struct afb_stored_req``` is opaque. - -It should require few code change. - -Also check the following chapter that explain that asynchronous (sub)calls -can be replaced by synchronous one, avoiding the need to store/unstore -requests. - -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. - -So when migrating to bindings version 2, a developer can consider -to replace the asynchronous requests (with asynchronous call back) -by synchronous ones. - -See functions ***afb_service_call_sync*** and ***afb_req_subcall_sync***. - -Optionally, removes explicit struct ------------------------------------ - -The new definitions now includes **typedefs** for common -structures, as shown on below sample: - -```C -typedef struct afb_daemon afb_daemon; -typedef struct afb_event afb_event; -typedef struct afb_arg afb_arg; -typedef struct afb_req afb_req; -typedef struct afb_service afb_service; -``` - -So you can remove the keyword **struct** if it bores you. - -Example: - -```C -static void verb(struct afb_req req) -{ - ... -} -``` - -Might become: - -```C -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. - -```diff -diff --git a/bindings/samples/HelloWorld.c b/bindings/samples/HelloWorld.c -index c6fa779..505aee3 100644 ---- a/bindings/samples/HelloWorld.c -+++ b/bindings/samples/HelloWorld.c -@@ -21,9 +21,9 @@ - - #include - -+#define AFB_BINDING_VERSION 2 - #include - --const struct afb_binding_interface *interface; - static pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER; - - struct event -@@ -79,7 +80,7 @@ static int event_add(const char *tag, const char *name) - strcpy(e->tag, tag); - - /* make the event */ -- 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 */ -@@ -140,7 +141,7 @@ static void pingBug (struct afb_req request) - 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)); - ping(request, json_object_get(query), "event"); - } - -@@ -288,38 +289,43 @@ static void exitnow (struct afb_req request) - exit(0); - } - -+static int preinit() -+{ -+ AFB_NOTICE("hello binding comes to live"); -+ return 0; -+} -+ -+static int init() -+{ -+ AFB_NOTICE("hello binding starting"); -+ return 0; -+} -+ - // NOTE: this sample does not use session to keep test a basic as possible - // in real application most APIs should be protected with AFB_SESSION_CHECK --static const struct afb_verb_desc_v1 verbs[]= { -- {"ping" , AFB_SESSION_NONE, pingSample , "Ping Application Framework"}, -- {"pingfail" , AFB_SESSION_NONE, pingFail , "Fails"}, -- {"pingnull" , AFB_SESSION_NONE, pingNull , "Return NULL"}, -- {"pingbug" , AFB_SESSION_NONE, pingBug , "Do a Memory Violation"}, -- {"pingJson" , AFB_SESSION_NONE, pingJson , "Return a JSON object"}, -- {"pingevent", AFB_SESSION_NONE, pingEvent , "Send an event"}, -- {"subcall", AFB_SESSION_NONE, subcall , "Call api/verb(args)"}, -- {"subcallsync", AFB_SESSION_NONE, subcallsync , "Call api/verb(args)"}, -- {"eventadd", AFB_SESSION_NONE, eventadd , "adds the event of 'name' for the 'tag'"}, -- {"eventdel", AFB_SESSION_NONE, eventdel , "deletes the event of 'tag'"}, -- {"eventsub", AFB_SESSION_NONE, eventsub , "subscribes to the event of 'tag'"}, -- {"eventunsub",AFB_SESSION_NONE, eventunsub , "unsubscribes to the event of 'tag'"}, -- {"eventpush", AFB_SESSION_NONE, eventpush , "pushs the event of 'tag' with the 'data'"}, -- {"exit", AFB_SESSION_NONE, exitnow , "exits from afb-daemon"}, -- {NULL} -+static const struct afb_verb_v2 verbs[]= { -+ { "ping" , pingSample , NULL, AFB_SESSION_NONE }, -+ { "pingfail" , pingFail , NULL, AFB_SESSION_NONE }, -+ { "pingnull" , pingNull , NULL, AFB_SESSION_NONE }, -+ { "pingbug" , pingBug , NULL, AFB_SESSION_NONE }, -+ { "pingJson" , pingJson , NULL, AFB_SESSION_NONE }, -+ { "pingevent", pingEvent , NULL, AFB_SESSION_NONE }, -+ { "subcall", subcall , NULL, AFB_SESSION_NONE }, -+ { "subcallsync", subcallsync, NULL, AFB_SESSION_NONE }, -+ { "eventadd", eventadd , NULL, AFB_SESSION_NONE }, -+ { "eventdel", eventdel , NULL, AFB_SESSION_NONE }, -+ { "eventsub", eventsub , NULL, AFB_SESSION_NONE }, -+ { "eventunsub", eventunsub , NULL, AFB_SESSION_NONE }, -+ { "eventpush", eventpush , NULL, AFB_SESSION_NONE }, -+ { "exit", exitnow , NULL, AFB_SESSION_NONE }, -+ { NULL} - }; - --static const struct afb_binding plugin_desc = { -- .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 - }; - --const struct afb_binding *afbBindingV1Register (const struct afb_binding_interface *itf) --{ -- interface = itf; -- NOTICE(interface, "hello plugin comes to live"); -- return &plugin_desc; --} -``` \ No newline at end of file diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/7_LEGACY_Binding_v2_references.md b/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/7_LEGACY_Binding_v2_references.md deleted file mode 100644 index c790db8..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/7_LEGACY_Binding_v2_references.md +++ /dev/null @@ -1,757 +0,0 @@ ---- -title: LEGACY Binding V2 references ---- - -# Structure for declaring binding ---------------------------------- - -### struct afb_binding_v2 - -The main structure, of type **afb_binding_v2**, for describing the binding -must be exported under the name **afbBindingV2**. - -This structure is defined as below. - -```C -/* - * Description of the bindings of type version 2 - */ -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 */ - 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 */ -}; -``` - -### struct afb_verb_v2 - -Each verb is described with a structure of type **afb_verb_v2** -defined below: - -```C -/* - * Description of one verb of the API provided by the binding - * This enumeration is valid for bindings of type version 2 - */ -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 */ - uint32_t session; /* authorization and session requirements of the verb */ -}; -``` - -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 - -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**. - -```C -struct afb_auth -{ - const enum afb_auth_type type; - union { - const char *text; - const unsigned loa; - const struct afb_auth *first; - }; - const struct afb_auth *next; -}; -``` - -The possible values for **type** is defined here: - -```C -/* - * Enum for Session/Token/Assurance middleware. - */ -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 */ -}; -``` - -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] } -}; -``` - -## Functions of class afb_daemon - -The 3 following functions are linked to libsystemd. -They allow use of **sd_event** features and access -to **sd_bus** features. - -```C -/* - * Retrieves the common systemd's event loop of AFB - */ -struct sd_event *afb_daemon_get_event_loop(); - -/* - * Retrieves the common systemd's user/session d-bus of AFB - */ -struct sd_bus *afb_daemon_get_user_bus(); - -/* - * Retrieves the common systemd's system d-bus of AFB - */ -struct sd_bus *afb_daemon_get_system_bus(); -``` - -The 2 following functions are linked to event management. -Broadcasting an event send it to any possible listener. - -```C -/* - * Broadcasts widely the event of 'name' with the data 'object'. - * 'object' can be NULL. - * - * For convenience, the function calls 'json_object_put' for 'object'. - * Thus, in the case where 'object' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * Calling this function is only forbidden during preinit. - * - * Returns the count of clients that received the event. - */ -int afb_daemon_broadcast_event(const char *name, struct json_object *object); - -/* - * Creates an event of 'name' and returns it. - * - * Calling this function is only forbidden during preinit. - * - * See afb_event_is_valid to check if there is an error. - */ -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** - -```C -/* - * Send a message described by 'fmt' and following parameters - * to the journal for the verbosity 'level'. - * - * 'file', 'line' and 'func' are indicators of position of the code in source files - * (see macros __FILE__, __LINE__ and __func__). - * - * 'level' is defined by syslog standard: - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - */ -void afb_daemon_verbose(int level, const char *file, int line, const char * func, const char *fmt, ...); -``` - -The 2 following functions MUST be used to access data of the bindings. - -```C -/* - * Get the root directory file descriptor. This file descriptor can - * be used with functions 'openat', 'fstatat', ... - */ -int afb_daemon_rootdir_get_fd(); - -/* - * Opens 'filename' within the root directory with 'flags' (see function openat) - * using the 'locale' definition (example: "jp,en-US") that can be NULL. - * Returns the file descriptor or -1 in case of error. - */ -int afb_daemon_rootdir_open_locale(const char *filename, int flags, const char *locale); -``` - -The following function is used to queue jobs. - -```C -/* - * Queue the job defined by 'callback' and 'argument' for being executed asynchronously - * in this thread (later) or in an other thread. - * If 'group' is not NUL, the jobs queued with a same value (as the pointer value 'group') - * are executed in sequence in the order of there submission. - * If 'timeout' is not 0, it represent the maximum execution time for the job in seconds. - * At first, the job is called with 0 as signum and the given argument. - * The job is executed with the monitoring of its time and some signals like SIGSEGV and - * SIGFPE. When a such signal is catched, the job is terminated and re-executed but with - * signum being the signal number (SIGALRM when timeout expired). - * - * Returns 0 in case of success or -1 in case of error. - */ -int afb_daemon_queue_job(void (*callback)(int signum, void *arg), void *argument, void *group, int timeout) -``` - -The following function must be used when a binding depends on other -bindings at its initialization. - -```C -/* - * Tells that it requires the API of "name" to exist - * and if 'initialized' is not null to be initialized. - * Calling this function is only allowed within init. - * Returns 0 in case of success or -1 in case of error. - */ -int afb_daemon_require_api(const char *name, int initialized) -``` - -This function allows to give a different name to the binding. -It can be called during pre-init. - -```C -/* - * Set the name of the API to 'name'. - * Calling this function is only allowed within preinit. - * Returns 0 in case of success or -1 in case of error. - */ -int afb_daemon_rename_api(const char *name); -``` - -## Functions of class afb_service - -The following functions allow services to call verbs of other -bindings for themselves. - -```C -/** - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. - * The result of the call is delivered to the 'callback' function with the 'callback_closure'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * The 'callback' receives 3 arguments: - * 1. 'closure' the user defined closure pointer 'callback_closure', - * 2. 'status' a status being 0 on success or negative when an error occurred, - * 2. 'result' the resulting data as a JSON object. - * - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param callback The to call on completion - * @param callback_closure The closure to pass to the callback - * - * @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); - -/** - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. - * 'result' will receive the response. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param result Where to store the result - should call json_object_put on it - - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see also 'afb_req_subcall' - */ -int afb_service_call_sync( - const char *api, - const char *verb, - struct json_object *args, - struct json_object **result); -``` - -## Functions of class afb_event - -This function checks whether the event is valid. -It must be used when creating events. - -```C -/* - * Checks wether the 'event' is valid or not. - * - * Returns 0 if not valid or 1 if valid. - */ -int afb_event_is_valid(struct afb_event event); -``` - -The two following functions are used to broadcast or push -event with its data. - -```C -/* - * Broadcasts widely the 'event' with the data 'object'. - * 'object' can be NULL. - * - * For convenience, the function calls 'json_object_put' for 'object'. - * Thus, in the case where 'object' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * Returns the count of clients that received the event. - */ -int afb_event_broadcast(struct afb_event event, struct json_object *object); - -/* - * Pushes the 'event' with the data 'object' to its observers. - * 'object' can be NULL. - * - * For convenience, the function calls 'json_object_put' for 'object'. - * Thus, in the case where 'object' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * Returns the count of clients that received the event. - */ -int afb_event_push(struct afb_event event, struct json_object *object); -``` - -The following function destroys the event. - -```C -/* - * Drops the data associated to the 'event' - * After calling this function, the event - * MUST NOT BE USED ANYMORE. - */ -void afb_event_drop(struct afb_event event); -``` - -This function allows to retrieve the exact name of the event. - -```C -/* - * Gets the name associated to the 'event'. - */ -const char *afb_event_name(struct afb_event event); -``` - -## Functions of class afb_req - -This function checks the validity of the **req**. - -```C -/* - * Checks wether the request 'req' is valid or not. - * - * Returns 0 if not valid or 1 if valid. - */ -int afb_req_is_valid(struct afb_req req); -``` - -The following functions retrieves parameters of the request. - -```C -/* - * Gets from the request 'req' the argument of 'name'. - * Returns a PLAIN structure of type 'struct afb_arg'. - * When the argument of 'name' is not found, all fields of result are set to NULL. - * When the argument of 'name' is found, the fields are filled, - * in particular, the field 'result.name' is set to 'name'. - * - * There is a special name value: the empty string. - * The argument of name "" is defined only if the request was made using - * an HTTP POST of Content-Type "application/json". In that case, the - * argument of name "" receives the value of the body of the HTTP request. - */ -struct afb_arg afb_req_get(struct afb_req req, const char *name); - -/* - * Gets from the request 'req' the string value of the argument of 'name'. - * Returns NULL if when there is no argument of 'name'. - * Returns the value of the argument of 'name' otherwise. - * - * Shortcut for: afb_req_get(req, name).value - */ -const char *afb_req_value(struct afb_req req, const char *name); - -/* - * Gets from the request 'req' the path for file attached to the argument of 'name'. - * Returns NULL if when there is no argument of 'name' or when there is no file. - * Returns the path of the argument of 'name' otherwise. - * - * Shortcut for: afb_req_get(req, name).path - */ -const char *afb_req_path(struct afb_req req, const char *name); - -/* - * Gets from the request 'req' the json object hashing the arguments. - * The returned object must not be released using 'json_object_put'. - */ -struct json_object *afb_req_json(struct afb_req req); -``` - -The following functions emit the reply to the request. - -```C -/* - * Sends a reply of kind success to the request 'req'. - * The status of the reply is automatically set to "success". - * Its send the object 'obj' (can be NULL) with an - * informational comment 'info (can also be NULL). - * - * For convenience, the function calls 'json_object_put' for 'obj'. - * Thus, in the case where 'obj' should remain available after - * the function returns, the function 'json_object_get' shall be used. - */ -void afb_req_success(struct afb_req req, struct json_object *obj, const char *info); - -/* - * Same as 'afb_req_success' but the 'info' is a formatting - * string followed by arguments. - * - * For convenience, the function calls 'json_object_put' for 'obj'. - * Thus, in the case where 'obj' should remain available after - * the function returns, the function 'json_object_get' shall be used. - */ -void afb_req_success_f(struct afb_req req, struct json_object *obj, const char *info, ...); - -/* - * Same as 'afb_req_success_f' but the arguments to the format 'info' - * are given as a variable argument list instance. - * - * For convenience, the function calls 'json_object_put' for 'obj'. - * Thus, in the case where 'obj' should remain available after - * the function returns, the function 'json_object_get' shall be used. - */ -void afb_req_success_v(struct afb_req req, struct json_object *obj, const char *info, va_list args); - -/* - * Sends a reply of kind failure to the request 'req'. - * The status of the reply is set to 'status' and an - * informational comment 'info' (can also be NULL) can be added. - * - * Note that calling afb_req_fail("success", info) is equivalent - * to call afb_req_success(NULL, info). Thus even if possible it - * is strongly recommended to NEVER use "success" for status. - */ -void afb_req_fail(struct afb_req req, const char *status, const char *info); - -/* - * Same as 'afb_req_fail' but the 'info' is a formatting - * string followed by arguments. - */ -void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...); - -/* - * Same as 'afb_req_fail_f' but the arguments to the format 'info' - * are given as a variable argument list instance. - */ -void afb_req_fail_v(struct afb_req req, const char *status, const char *info, va_list args); -``` - -The following functions handle the session data. - -```C -/* - * Gets the pointer stored by the binding for the session of 'req'. - * When the binding has not yet recorded a pointer, NULL is returned. - */ -void *afb_req_context_get(struct afb_req req); - -/* - * Stores for the binding the pointer 'context' to the session of 'req'. - * The function 'free_context' will be called when the session is closed - * or if binding stores an other pointer. - */ -void afb_req_context_set(struct afb_req req, void *context, void (*free_context)(void*)); - -/* - * Gets the pointer stored by the binding for the session of 'req'. - * If the stored pointer is NULL, indicating that no pointer was - * already stored, afb_req_context creates a new context by calling - * the function 'create_context' and stores it with the freeing function - * 'free_context'. - */ -void *afb_req_context(struct afb_req req, void *(*create_context)(), void (*free_context)(void*)); - -/* - * Frees the pointer stored by the binding for the session of 'req' - * and sets it to NULL. - * - * Shortcut for: afb_req_context_set(req, NULL, NULL) - */ -void afb_req_context_clear(struct afb_req req); - -/* - * Closes the session associated with 'req' - * and delete all associated contexts. - */ -void afb_req_session_close(struct afb_req req); - -/* - * Sets the level of assurance of the session of 'req' - * to 'level'. The effect of this function is subject of - * security policies. - * Returns 1 on success or 0 if failed. - */ -int afb_req_session_set_LOA(struct afb_req req, unsigned level); -``` - -The 4 following functions must be used for asynchronous handling requests. - -```C -/* - * Adds one to the count of references of 'req'. - * This function MUST be called by asynchronous implementations - * of verbs if no reply was sent before returning. - */ -void afb_req_addref(struct afb_req req); - -/* - * Substracts one to the count of references of 'req'. - * This function MUST be called by asynchronous implementations - * of verbs after sending the asynchronous reply. - */ -void afb_req_unref(struct afb_req req); - -/* - * Stores 'req' on heap for asynchronous use. - * Returns a handler to the stored 'req' or NULL on memory depletion. - * The count of reference to 'req' is incremented on success - * (see afb_req_addref). - */ -struct afb_stored_req *afb_req_store(struct afb_req req); - -/* - * Retrieves the afb_req stored at 'sreq'. - * Returns the stored request. - * The count of reference is UNCHANGED, thus, the - * function 'afb_req_unref' should be called on the result - * after that the asynchronous reply if sent. - */ -struct afb_req afb_req_unstore(struct afb_stored_req *sreq); -``` - -The two following functions are used to associate client with events -(subscription). - -```C -/* - * Establishes for the client link identified by 'req' a subscription - * to the 'event'. - * Returns 0 in case of successful subscription or -1 in case of error. - */ -int afb_req_subscribe(struct afb_req req, struct afb_event event); - -/* - * Revokes the subscription established to the 'event' for the client - * link identified by 'req'. - * Returns 0 in case of successful subscription or -1 in case of error. - */ -int afb_req_unsubscribe(struct afb_req req, struct afb_event event); -``` - -The following functions must be used to make request in the name of the -client (with its permissions). - -```C -/* - * 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'. - * On completion, the function 'callback' is invoked with the - * 'closure' given at call and two other parameters: 'iserror' and 'result'. - * 'status' is 0 on success or negative when on an error reply. - * 'result' is the json object of the reply, you must not call json_object_put - * on the result. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * See also: - * - 'afb_req_subcall_req' that is convenient to keep request alive automatically. - * - 'afb_req_subcall_sync' the synchronous version - */ -void afb_req_subcall( - struct afb_req req, - const char *api, - const char *verb, - struct json_object *args, - void (*callback)(void *closure, int status, struct json_object *result), - void *closure); - -/* - * 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'. - * On completion, the function 'callback' is invoked with the - * original request 'req', the 'closure' given at call and two - * other parameters: 'iserror' and 'result'. - * 'status' is 0 on success or negative when on an error reply. - * 'result' is the json object of the reply, you must not call json_object_put - * on the result. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * See also: - * - 'afb_req_subcall' that doesn't keep request alive automatically. - * - 'afb_req_subcall_sync' the synchronous version - */ -static inline void afb_req_subcall_req(struct afb_req req, const char *api, const char *verb, struct json_object *args, void (*callback)(void *closure, int iserror, struct json_object *result, struct afb_req req), void *closure) -{ - req.itf->subcall_req(req.closure, api, verb, args, callback, closure); -} - -/* - * 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 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'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * See also: - * - 'afb_req_subcall_req' that is convenient to keep request alive automatically. - * - 'afb_req_subcall' that doesn't keep request alive automatically. - */ -int afb_req_subcall_sync( - struct afb_req req, - const char *api, - const char *verb, - struct json_object *args, - struct json_object **result); -``` - -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** - -```C -/* - * Send associated to 'req' a message described by 'fmt' and following parameters - * to the journal for the verbosity 'level'. - * - * 'file', 'line' and 'func' are indicators of position of the code in source files - * (see macros __FILE__, __LINE__ and __func__). - * - * 'level' is defined by syslog standard: - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - */ -void afb_req_verbose(struct afb_req req, int level, const char *file, int line, const char * func, const char *fmt, ...); -``` - -The functions below allow a binding involved in the platform security -to explicitly check a permission of a client or to get the calling -application identity. - -```C -/* - * Check whether the 'permission' is granted or not to the client - * identified by 'req'. - * - * Returns 1 if the permission is granted or 0 otherwise. - */ -int afb_req_has_permission(struct afb_req req, const char *permission); - -/* - * Get the application identifier of the client application for the - * request 'req'. - * - * Returns the application identifier or NULL when the application - * can not be identified. - * - * The returned value if not NULL must be freed by the caller - */ -char *afb_req_get_application_id(struct afb_req req); - -/* - * Get the user identifier (UID) of the client application for the - * request 'req'. - * - * Returns -1 when the application can not be identified. - */ -int afb_req_get_uid(struct afb_req req); -``` - -## Logging macros - -The following macros must be used for logging: - -```C -AFB_ERROR(fmt,...) -AFB_WARNING(fmt,...) -AFB_NOTICE(fmt,...) -AFB_INFO(fmt,...) -AFB_DEBUG(fmt,...) -``` - -The following macros can be used for logging in the context -of a request **req** of type **afb_req**: - -```C -AFB_REQ_ERROR(req,fmt,...) -AFB_REQ_WARNING(req,fmt,...) -AFB_REQ_NOTICE(req,fmt,...) -AFB_REQ_INFO(req,fmt,...) -AFB_REQ_DEBUG(req,fmt,...) -``` - -By default, the logging macros add file, line and function -indication. \ No newline at end of file diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/images/basis.svg b/docs/3_Developer_Guides/2_Application_Framework_Binder/images/basis.svg deleted file mode 100644 index 0d42d76..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/images/basis.svg +++ /dev/null @@ -1,356 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - APPLICATION - - - - - - - - BINDERafb-daemon - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - SECURITYCONTEXT - - - - - - http - - - - - - ws - - - - - - - - \ No newline at end of file diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/images/interconnection.svg b/docs/3_Developer_Guides/2_Application_Framework_Binder/images/interconnection.svg deleted file mode 100644 index 4a10217..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/images/interconnection.svg +++ /dev/null @@ -1,854 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - APPLICATION - - - - - - - - BINDERafb-daemon - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - SECURITYCONTEXT - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - APPLICATION - - - - - - - - BINDERafb-daemon - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - SECURITYCONTEXT - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - APPLICATION - - - - - - - - BINDERafb-daemon - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - SECURITYCONTEXT - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - APPLICATION - - - - - - - - BINDERafb-daemon - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - SECURITYCONTEXT - - - - - - - - - interconnectiondbus, ws,bus1, tls,... - - - - - - - - A - - - - - - - - C - - - - - - - - B - - - - - - - - D - - - - - - - - \ No newline at end of file diff --git a/docs/3_Developer_Guides/2_Application_Framework_Binder/images/signaling-basis.svg b/docs/3_Developer_Guides/2_Application_Framework_Binder/images/signaling-basis.svg deleted file mode 100644 index b13fcf1..0000000 --- a/docs/3_Developer_Guides/2_Application_Framework_Binder/images/signaling-basis.svg +++ /dev/null @@ -1,145 +0,0 @@ - - - - - - - request-data - - - - - - client 1 - - - - - - - - client 2 - - - - - - - - : framework - - - - - - - - signaling agent - - - - - - - - - - - request-data - - - - - - afb_daemon_make_event - - - - - - - - - afb_req_subscribe - - - - - reply of request-data - - - - - - afb_req_subscribe - - - - - reply of request-data - - - - - - device - - - - - - - - - setup - - - - - << wake up >> - - - - - afb_event_push - - - - - << event >> - - - - - << event >> - - - - - reply of afb_event_push - - - - - - - - - - - - - - - - - - - - - - - - - - -- cgit 1.2.3-korg