Types and globals

typedef struct afb_binding_v4 afb_binding_t;

/**
 * Description of the bindings of type version 4
 */
struct afb_binding_v4
{
	/** 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_v4 *verbs;

	/** callback at load of the binding */
	afb_api_callback_x4_t mainctl;

	/** userdata for afb_api_ */
	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;
};

typedef struct afb_verb_v4 afb_verb_t;

/**
 * Description of one verb as provided for binding API version 4
 */
struct afb_verb_v4
{
	/** name of the verb, NULL only at end of the array */
	const char *verb;

	/** callback function implementing the verb */
	afb_req_callback_x4_t callback;

	/** 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;
};

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;
};

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
};

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] }
};

typedef enum afb_ctlid afb_ctlid_t;

enum afb_ctlid
{
	/** called on root entries, the entries not linked to an API */
	afb_ctlid_Root_Entry = 0,

	/** called for the preinit of an API, has a companion argument */
	afb_ctlid_Pre_Init = 1,

	/** called for init */
	afb_ctlid_Init = 2,

	/** called when required classes are ready */
	afb_ctlid_Class_Ready = 3,

	/** called when an event is not handled */
	afb_ctlid_Orphan_Event = 4,

	/** called when shuting down */
	afb_ctlid_Exiting = 5
};

typedef const union afb_ctlarg *afb_ctlarg_t;

union afb_ctlarg
{
	/**
	 * structure for message afb_ctlid_Root_Entry
	 */
	struct {
		/** path of the binding */
		const char *path;
	} root_entry;

	/**
	 * structure for message afb_ctlid_Pre_Init
	 */
	struct {
		/** path of the binding */
		const char *path;
	} pre_init;

	/**
	 * structure for message afb_ctlid_Orphan_Event
	 */
	struct {
		/** name of the of the orphan event */
		const char *name;
	} orphan_event;

	/**
	 * structure for message afb_ctlid_Exiting
	 */
	struct {
		/** exiting code */
		int code;
	} exiting;
};

/**
 * Main api callback function.
 *
 * @param api       the api that receive the callback
 * @param ctlid     identifier of the reason of the call (@see afb_ctlid)
 * @param ctlarg    data associated to the call
 * @param userdata  the userdata of the api (@see afb_api_get_userdata)
 *
 * @return a value that must be negative if an error occured. The
 *         return value is important when ctlid relates to an initialisation
 *         step, i.e. when it has one of the following predefined values:
 *         afb_ctlid_Root_Entry, afb_ctlid_Pre_Init, afb_ctlid_Init.
 */
typedef int (*afb_api_callback_t)(
		afb_api_t api,
		afb_ctlid_t ctlid,
		afb_ctlarg_t ctlarg,
		void *userdata);

/**
 * Request handling callback used for verbs.
 *
 * @param req      the request to process
 * @param nparams  the count of parameter data of the request
 * @param params   the array of parameter data of the request
 */
typedef void (*afb_req_callback_t)(
		afb_req_t req,
		unsigned nparams,
		afb_data_t const params[]);

/**
 * Callback for receiving asynchronous results of a call.
 *
 * @param closure  the closure value given at call
 * @param status   the status of the call, negative on error
 * @param nreplies the count of replied data
 * @param replies  the array of replied data
 * @param api      the api that made the call
 */
typedef void (*afb_call_callback_t)(
		void *closure,
		int status,
		unsigned nreplies,
		afb_data_t const replies[],
		afb_api_t api);

/**
 * Callback for receiving asynchronous results of a subcall.
 *
 * @param closure  the closure value given at subcall
 * @param status   the status of the subcall, negative on error
 * @param nreplies the count of replied data
 * @param replies  the array of replied data
 * @param req      the req that made the subcall
 */
typedef void (*afb_subcall_callback_t)(
		void *closure,
		int status,
		unsigned nreplies,
		afb_data_t const replies[],
		afb_req_t req);

/**
 * Callback for receiving result of checking of permissions.
 *
 * @param closure  the closure value given at check
 * @param status   the status of the check, negative when rejected
 * @param req      the req that made the check
 */
typedef void (*afb_check_callback_t)(
		void *closure,
		int status,
		afb_req_t req);

/**
 * Callback for handling events.
 *
 * @param closure  the closure value given at creation of the handler
 * @param event_name name of the event
 * @param nparams  the count of parameter data of the event
 * @param params   the array of parameter data of the event
 * @param api      the api that holds the handler
 */
typedef void (*afb_event_handler_t)(
		void *closure,
		const char *event_name,
		unsigned nparams,
		afb_data_t const params[],
		afb_api_t api);

/**
 * The type afb_type_converter_t denote a conversion callback.
 *
 * A conversion callback receives 4 parameters:
 *
 * @param closure   A closure defined when converter is declared
 * @param from      The data to convert
 * @param type      The type to convert to
 * @param to        Where to store the result of the conversion
 *
 * @return It should return an integer status of 0 in case of success
 *         or a negative value indicating the error.
 */
typedef int (*afb_type_converter_t)(
		void *closure,
		afb_data_t from,
		afb_type_t type,
		afb_data_t *to);

/**
 * The type afb_type_updater_t denote a conversion callback that is able
 * to update the target instead of creating it.
 *
 * A conversion callback receives 4 parameters:
 *
 * @param  closure   A closure defined when converter is declared
 * @param  from      The data of reference
 * @param  type      The type of the data to update
 * @param  to        the existing data to update from the given reference
 *
 * @return It should return an integer status of 0 in case of success
 *         or a negative value indicating the error.
 */
typedef int (*afb_type_updater_t)(
		void *closure,
		afb_data_t from,
		afb_type_t type,
		afb_data_t to);

/**
 * Callbacks of file event handlers
 *
 * These callbacks are called when an event occurs on the handled
 * file descriptor.
 *
 * @param efd the file event handler object
 * @param fd the file descriptor index
 * @param revents the received events
 * @param closure the closure given at creation
 */
typedef void (*afb_evfd_handler_t)(
		afb_evfd_t efd,
		int fd,
		uint32_t revents,
		void *closure);

/**
 * Callbacks of timers
 *
 * These callbacks are called when a programmed time even occurs.
 *
 * @param timer the timer object
 * @param closure the closure given at creation
 * @param decount reverse index of the event: zero for infinite timer
 *                or a decreasing value finishing with 1
 */
typedef void (*afb_timer_handler_t)(
		afb_timer_t timer,
		void *closure,
		int decount);