docs/reference-v3/types-and-globals.md

   1 # Types and globals
   2
   3 ## The global afbBindingRoot
   4
   5 The global **afbBindingRoot** of type **afb_api_t** is always implicitly
   6 defined for bindings of version 3 or upper. It records the root api of
   7 the binding.
   8
   9 When the binding has a defined **afbBindingExport**,  the root api
  10 **afbBindingRoot** is the **afb_pi_t** relative to the api created for
  11 this static description.
  12
  13 When the binding has no defined **afbBindingExport**, the root api is
  14 a virtual api representing the shared object of the binding. In that case
  15 the name of the api is the path of the shared object. Its use is restricted
  16 but allows log messages.
  17
  18 ## The global afbBindingExport
  19
  20 The global **afbBindingExport** is not mandatory.
  21
  22 If **afbBindingExport** is defined and exported, it must be of the type
  23 **const afb_binding_t** and must describe the *root* api of the binding.
  24
  25 ## The type afb_api_t
  26
  27 Bindings now can declare more than one api. The counter part is that
  28 a new handle is needed to manage apis. These handles are of the type
  29 **afb_api_t**.
  30
  31 It is defined as below.
  32
  33 ```C
  34 typedef struct afb_api_x3 afb_api_t;
  35 ```
  36
  37 ## The type afb_binding_t
  38
  39 The main structure, of type **afb_binding_t**, for describing the binding
  40 must be exported under the name **afbBindingExport**.
  41
  42 This structure is defined as below.
  43
  44 ```C
  45 typedef struct afb_binding_v3 afb_binding_t;
  46 ```
  47
  48 Where:
  49
  50 ```C
  51 /**
  52  * Description of the bindings of type version 3
  53  */
  54 struct afb_binding_v3
  55 {
  56         /** api name for the binding, can't be NULL */
  57         const char *api;
  58
  59         /** textual specification of the binding, can be NULL */
  60         const char *specification;
  61
  62         /** some info about the api, can be NULL */
  63         const char *info;
  64
  65         /** array of descriptions of verbs terminated by a NULL name, can be NULL */
  66         const struct afb_verb_v3 *verbs;
  67
  68         /** callback at load of the binding */
  69         int (*preinit)(struct afb_api_x3 *api);
  70
  71         /** callback for starting the service */
  72         int (*init)(struct afb_api_x3 *api);
  73
  74         /** callback for handling events */
  75         void (*onevent)(struct afb_api_x3 *api, const char *event, struct json_object *object);
  76
  77         /** userdata for afb_api_x3 */
  78         void *userdata;
  79
  80         /** space separated list of provided class(es) */
  81         const char *provide_class;
  82
  83         /** space separated list of required class(es) */
  84         const char *require_class;
  85
  86         /** space separated list of required API(es) */
  87         const char *require_api;
  88
  89         /** avoids concurrent requests to verbs */
  90         unsigned noconcurrency: 1;
  91 };
  92 ```
  93
  94 ## The type afb_verb_t
  95
  96 Each verb is described with a structure of type **afb_verb_t**
  97 defined below:
  98
  99 ```C
 100 typedef struct afb_verb_v3 afb_verb_t;
 101 ```
 102
 103 ```C
 104 /**
 105  * Description of one verb as provided for binding API version 3
 106  */
 107 struct afb_verb_v3
 108 {
 109         /** name of the verb, NULL only at end of the array */
 110         const char *verb;
 111
 112         /** callback function implementing the verb */
 113         void (*callback)(afb_req_t_x2 *req);
 114
 115         /** required authorization, can be NULL */
 116         const struct afb_auth *auth;
 117
 118         /** some info about the verb, can be NULL */
 119         const char *info;
 120
 121         /**< data for the verb callback */
 122         void *vcbdata;
 123
 124         /** authorization and session requirements of the verb */
 125         uint16_t session;
 126
 127         /** is the verb glob name */
 128         uint16_t glob: 1;
 129 };
 130 ```
 131
 132 The **session** flags is one of the constant defined below:
 133
 134 | Name                   | Description
 135 |:----------------------:|------------------------------------------------------
 136 | AFB_SESSION_NONE       | no flag, synonym to 0
 137 | AFB_SESSION_LOA_0      | Requires the LOA to be 0 or more, synonym to 0 or AFB_SESSION_NONE
 138 | AFB_SESSION_LOA_1      | Requires the LOA to be 1 or more
 139 | AFB_SESSION_LOA_2      | Requires the LOA to be 2 or more
 140 | AFB_SESSION_LOA_3      | Requires the LOA to be 3 or more
 141 | AFB_SESSION_CHECK      | Requires the token to be set and valid
 142 | AFB_SESSION_REFRESH    | Implies a token refresh
 143 | AFB_SESSION_CLOSE      | Implies closing the session after request processed
 144
 145 The LOA (Level Of Assurance) is set, by binding api, using the function **afb_req_session_set_LOA**.
 146
 147 The session can be closed, by binding api, using the function **afb_req_session_close**.
 148
 149 ## The types afb_auth_t and afb_auth_type_t
 150
 151 The structure **afb_auth_t** is used within verb description to
 152 set security requirements.
 153 The interpretation of the structure depends on the value of the field **type**.
 154
 155 ```C
 156 typedef struct afb_auth afb_auth_t;
 157
 158 /**
 159  * Definition of an authorization entry
 160  */
 161 struct afb_auth
 162 {
 163         /** type of entry @see afb_auth_type */
 164         enum afb_auth_type type;
 165
 166         union {
 167                 /** text when @ref type == @ref afb_auth_Permission */
 168                 const char *text;
 169
 170                 /** level of assurancy when @ref type ==  @ref afb_auth_LOA */
 171                 unsigned loa;
 172
 173                 /** first child when @ref type in { @ref afb_auth_Or, @ref afb_auth_And, @ref afb_auth_Not } */
 174                 const struct afb_auth *first;
 175         };
 176
 177         /** second child when @ref type in { @ref afb_auth_Or, @ref afb_auth_And } */
 178         const struct afb_auth *next;
 179 };
 180
 181 ```
 182
 183 The possible values for **type** is defined here:
 184
 185 ```C
 186 typedef enum afb_auth_type afb_auth_type_t;
 187
 188 /**
 189  * Enumeration  for authority (Session/Token/Assurance) definitions.
 190  *
 191  * @see afb_auth
 192  */
 193 enum afb_auth_type
 194 {
 195         /** never authorized, no data */
 196         afb_auth_No = 0,
 197
 198         /** authorized if token valid, no data */
 199         afb_auth_Token,
 200
 201         /** authorized if LOA greater than data 'loa' */
 202         afb_auth_LOA,
 203
 204         /** authorized if permission 'text' is granted */
 205         afb_auth_Permission,
 206
 207         /** authorized if 'first' or 'next' is authorized */
 208         afb_auth_Or,
 209
 210         /** authorized if 'first' and 'next' are authorized */
 211         afb_auth_And,
 212
 213         /** authorized if 'first' is not authorized */
 214         afb_auth_Not,
 215
 216         /** always authorized, no data */
 217         afb_auth_Yes
 218 };
 219 ```
 220
 221 Example:
 222
 223 ```C
 224 static const afb_auth_t myauth[] = {
 225     { .type = afb_auth_Permission, .text = "urn:AGL:permission:me:public:set" },
 226     { .type = afb_auth_Permission, .text = "urn:AGL:permission:me:public:get" },
 227     { .type = afb_auth_Or, .first = &myauth[1], .next = &myauth[0] }
 228 };
 229 ```
 230
 231
 232 ## The type afb_req_subcall_flags_t
 233
 234 This is an enumeration that defines bit's positions for setting behaviour
 235 of subcalls.
 236
 237 | flag                       | value | description
 238 |----------------------------|-------|--------------
 239 | afb_req_subcall_catch_events | 1 | the calling API wants to receive the events from subscription
 240 | afb_req_subcall_pass_events  | 2 | the original request will receive the events from subscription
 241 | afb_req_subcall_on_behalf    | 4 | the calling API wants to use the credentials of the original request
 242 | afb_req_subcall_api_session  | 8 | the calling API wants to use its session instead of the one of the original request
 243