3 title: Types and globals
5 https://git.automotivelinux.org/src/app-framework-binder/plain/docs/reference-v3/types-and-globals.md?h=master
8 <!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/apis_services/master/app-framework-binder-developer-guides-api-services-book.yml -->
12 ## The global afbBindingRoot
14 The global **afbBindingRoot** of type **afb_api_t** is always implicitly
15 defined for bindings of version 3 or upper. It records the root api of
18 When the binding has a defined **afbBindingExport**, the root api
19 **afbBindingRoot** is the **afb_pi_t** relative to the api created for
20 this static description.
22 When the binding has no defined **afbBindingExport**, the root api is
23 a virtual api representing the shared object of the binding. In that case
24 the name of the api is the path of the shared object. Its use is restricted
25 but allows log messages.
27 ## The global afbBindingExport
29 The global **afbBindingExport** is not mandatory.
31 If **afbBindingExport** is defined and exported, it must be of the type
32 **const afb_binding_t** and must describe the *root* api of the binding.
36 Bindings now can declare more than one api. The counter part is that
37 a new handle is needed to manage apis. These handles are of the type
40 It is defined as below.
43 typedef struct afb_api_x3 afb_api_t;
46 ## The type afb_binding_t
48 The main structure, of type **afb_binding_t**, for describing the binding
49 must be exported under the name **afbBindingExport**.
51 This structure is defined as below.
54 typedef struct afb_binding_v3 afb_binding_t;
61 * Description of the bindings of type version 3
65 /** api name for the binding, can't be NULL */
68 /** textual specification of the binding, can be NULL */
69 const char *specification;
71 /** some info about the api, can be NULL */
74 /** array of descriptions of verbs terminated by a NULL name, can be NULL */
75 const struct afb_verb_v3 *verbs;
77 /** callback at load of the binding */
78 int (*preinit)(struct afb_api_x3 *api);
80 /** callback for starting the service */
81 int (*init)(struct afb_api_x3 *api);
83 /** callback for handling events */
84 void (*onevent)(struct afb_api_x3 *api, const char *event, struct json_object *object);
86 /** userdata for afb_api_x3 */
89 /** space separated list of provided class(es) */
90 const char *provide_class;
92 /** space separated list of required class(es) */
93 const char *require_class;
95 /** space separated list of required API(es) */
96 const char *require_api;
98 /** avoids concurrent requests to verbs */
99 unsigned noconcurrency: 1;
103 ## The type afb_verb_t
105 Each verb is described with a structure of type **afb_verb_t**
109 typedef struct afb_verb_v3 afb_verb_t;
114 * Description of one verb as provided for binding API version 3
118 /** name of the verb, NULL only at end of the array */
121 /** callback function implementing the verb */
122 void (*callback)(afb_req_t_x2 *req);
124 /** required authorization, can be NULL */
125 const struct afb_auth *auth;
127 /** some info about the verb, can be NULL */
130 /**< data for the verb callback */
133 /** authorization and session requirements of the verb */
136 /** is the verb glob name */
141 The **session** flags is one of the constant defined below:
144 |:----------------------:|------------------------------------------------------
145 | AFB_SESSION_NONE | no flag, synonym to 0
146 | AFB_SESSION_LOA_0 | Requires the LOA to be 0 or more, synonym to 0 or AFB_SESSION_NONE
147 | AFB_SESSION_LOA_1 | Requires the LOA to be 1 or more
148 | AFB_SESSION_LOA_2 | Requires the LOA to be 2 or more
149 | AFB_SESSION_LOA_3 | Requires the LOA to be 3 or more
150 | AFB_SESSION_CHECK | Requires the token to be set and valid
151 | AFB_SESSION_REFRESH | Implies a token refresh
152 | AFB_SESSION_CLOSE | Implies closing the session after request processed
154 The LOA (Level Of Assurance) is set, by binding api, using the function **afb_req_session_set_LOA**.
156 The session can be closed, by binding api, using the function **afb_req_session_close**.
158 ## The types afb_auth_t and afb_auth_type_t
160 The structure **afb_auth_t** is used within verb description to
161 set security requirements.
162 The interpretation of the structure depends on the value of the field **type**.
165 typedef struct afb_auth afb_auth_t;
168 * Definition of an authorization entry
172 /** type of entry @see afb_auth_type */
173 enum afb_auth_type type;
176 /** text when @ref type == @ref afb_auth_Permission */
179 /** level of assurancy when @ref type == @ref afb_auth_LOA */
182 /** first child when @ref type in { @ref afb_auth_Or, @ref afb_auth_And, @ref afb_auth_Not } */
183 const struct afb_auth *first;
186 /** second child when @ref type in { @ref afb_auth_Or, @ref afb_auth_And } */
187 const struct afb_auth *next;
192 The possible values for **type** is defined here:
195 typedef enum afb_auth_type afb_auth_type_t;
198 * Enumeration for authority (Session/Token/Assurance) definitions.
204 /** never authorized, no data */
207 /** authorized if token valid, no data */
210 /** authorized if LOA greater than or equal to data 'loa' */
213 /** authorized if permission 'text' is granted */
216 /** authorized if 'first' or 'next' is authorized */
219 /** authorized if 'first' and 'next' are authorized */
222 /** authorized if 'first' is not authorized */
225 /** always authorized, no data */
233 static const afb_auth_t myauth[] = {
234 { .type = afb_auth_Permission, .text = "urn:AGL:permission:me:public:set" },
235 { .type = afb_auth_Permission, .text = "urn:AGL:permission:me:public:get" },
236 { .type = afb_auth_Or, .first = &myauth[1], .next = &myauth[0] }
241 ## The type afb_req_subcall_flags_t
243 This is an enumeration that defines bit's positions for setting behaviour
246 | flag | value | description
247 |----------------------------|-------|--------------
248 | afb_req_subcall_catch_events | 1 | the calling API wants to receive the events from subscription
249 | afb_req_subcall_pass_events | 2 | the original request will receive the events from subscription
250 | afb_req_subcall_on_behalf | 4 | the calling API wants to use the credentials of the original request
251 | afb_req_subcall_api_session | 8 | the calling API wants to use its session instead of the one of the original request