docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/1_Types_and_globals.md

   1 ---
   2 edit_link: ''
   3 title: Types and globals
   4 origin_url: >-
   5   https://git.automotivelinux.org/src/app-framework-binder/plain/docs/reference-v3/types-and-globals.md?h=master
   6 ---
   7
   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 -->
   9
  10 # Types and globals
  11
  12 ## The global afbBindingRoot
  13
  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
  16 the binding.
  17
  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.
  21
  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.
  26
  27 ## The global afbBindingExport
  28
  29 The global **afbBindingExport** is not mandatory.
  30
  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.
  33
  34 ## The type afb_api_t
  35
  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
  38 **afb_api_t**.
  39
  40 It is defined as below.
  41
  42 ```C
  43 typedef struct afb_api_x3 afb_api_t;
  44 ```
  45
  46 ## The type afb_binding_t
  47
  48 The main structure, of type **afb_binding_t**, for describing the binding
  49 must be exported under the name **afbBindingExport**.
  50
  51 This structure is defined as below.
  52
  53 ```C
  54 typedef struct afb_binding_v3 afb_binding_t;
  55 ```
  56
  57 Where:
  58
  59 ```C
  60 /**
  61  * Description of the bindings of type version 3
  62  */
  63 struct afb_binding_v3
  64 {
  65         /** api name for the binding, can't be NULL */
  66         const char *api;
  67
  68         /** textual specification of the binding, can be NULL */
  69         const char *specification;
  70
  71         /** some info about the api, can be NULL */
  72         const char *info;
  73
  74         /** array of descriptions of verbs terminated by a NULL name, can be NULL */
  75         const struct afb_verb_v3 *verbs;
  76
  77         /** callback at load of the binding */
  78         int (*preinit)(struct afb_api_x3 *api);
  79
  80         /** callback for starting the service */
  81         int (*init)(struct afb_api_x3 *api);
  82
  83         /** callback for handling events */
  84         void (*onevent)(struct afb_api_x3 *api, const char *event, struct json_object *object);
  85
  86         /** userdata for afb_api_x3 */
  87         void *userdata;
  88
  89         /** space separated list of provided class(es) */
  90         const char *provide_class;
  91
  92         /** space separated list of required class(es) */
  93         const char *require_class;
  94
  95         /** space separated list of required API(es) */
  96         const char *require_api;
  97
  98         /** avoids concurrent requests to verbs */
  99         unsigned noconcurrency: 1;
 100 };
 101 ```
 102
 103 ## The type afb_verb_t
 104
 105 Each verb is described with a structure of type **afb_verb_t**
 106 defined below:
 107
 108 ```C
 109 typedef struct afb_verb_v3 afb_verb_t;
 110 ```
 111
 112 ```C
 113 /**
 114  * Description of one verb as provided for binding API version 3
 115  */
 116 struct afb_verb_v3
 117 {
 118         /** name of the verb, NULL only at end of the array */
 119         const char *verb;
 120
 121         /** callback function implementing the verb */
 122         void (*callback)(afb_req_t_x2 *req);
 123
 124         /** required authorization, can be NULL */
 125         const struct afb_auth *auth;
 126
 127         /** some info about the verb, can be NULL */
 128         const char *info;
 129
 130         /**< data for the verb callback */
 131         void *vcbdata;
 132
 133         /** authorization and session requirements of the verb */
 134         uint16_t session;
 135
 136         /** is the verb glob name */
 137         uint16_t glob: 1;
 138 };
 139 ```
 140
 141 The **session** flags is one of the constant defined below:
 142
 143 | Name                   | Description
 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
 153
 154 The LOA (Level Of Assurance) is set, by binding api, using the function **afb_req_session_set_LOA**.
 155
 156 The session can be closed, by binding api, using the function **afb_req_session_close**.
 157
 158 ## The types afb_auth_t and afb_auth_type_t
 159
 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**.
 163
 164 ```C
 165 typedef struct afb_auth afb_auth_t;
 166
 167 /**
 168  * Definition of an authorization entry
 169  */
 170 struct afb_auth
 171 {
 172         /** type of entry @see afb_auth_type */
 173         enum afb_auth_type type;
 174
 175         union {
 176                 /** text when @ref type == @ref afb_auth_Permission */
 177                 const char *text;
 178
 179                 /** level of assurancy when @ref type ==  @ref afb_auth_LOA */
 180                 unsigned loa;
 181
 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;
 184         };
 185
 186         /** second child when @ref type in { @ref afb_auth_Or, @ref afb_auth_And } */
 187         const struct afb_auth *next;
 188 };
 189
 190 ```
 191
 192 The possible values for **type** is defined here:
 193
 194 ```C
 195 typedef enum afb_auth_type afb_auth_type_t;
 196
 197 /**
 198  * Enumeration  for authority (Session/Token/Assurance) definitions.
 199  *
 200  * @see afb_auth
 201  */
 202 enum afb_auth_type
 203 {
 204         /** never authorized, no data */
 205         afb_auth_No = 0,
 206
 207         /** authorized if token valid, no data */
 208         afb_auth_Token,
 209
 210         /** authorized if LOA greater than or equal to data 'loa' */
 211         afb_auth_LOA,
 212
 213         /** authorized if permission 'text' is granted */
 214         afb_auth_Permission,
 215
 216         /** authorized if 'first' or 'next' is authorized */
 217         afb_auth_Or,
 218
 219         /** authorized if 'first' and 'next' are authorized */
 220         afb_auth_And,
 221
 222         /** authorized if 'first' is not authorized */
 223         afb_auth_Not,
 224
 225         /** always authorized, no data */
 226         afb_auth_Yes
 227 };
 228 ```
 229
 230 Example:
 231
 232 ```C
 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] }
 237 };
 238 ```
 239
 240
 241 ## The type afb_req_subcall_flags_t
 242
 243 This is an enumeration that defines bit's positions for setting behaviour
 244 of subcalls.
 245
 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
 252