# Binding Reference
## Structure for declaring binding
### 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;
};
```
### struct 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:
- 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**.
### 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 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] }
};
```
## 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 if active
*/
struct sd_bus *afb_daemon_get_user_bus();
/*
* Retrieves the common systemd's system d-bus of AFB if active or NULL
*/
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 client