From 7e0abe76db7b90369429bf387d7aad0fb5a42328 Mon Sep 17 00:00:00 2001 From: José Bollo Date: Thu, 9 Jun 2016 07:54:31 +0200 Subject: Events: refactoring MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This new version allows to subscribe a client for an event. The event should first be created for the API (the API's prefix is added) using 'afb_daemon_make_event'. After that, plugins can subscribe or unsubscribe their clients (identified through requests) to the events that it generates. See 'afb_req_subscribe' and 'afb_req_unsubscribe'. Events created by 'afb_daemon_make_event' can be widely broadcasted using 'afb_event_broadcast' or pushed only to suscribers using 'afb_event_push'. Events can be destroyed using 'afb_event_drop'. Change-Id: I7c0bed5e625c2052dcd81c6bfe960def1fa032f3 Signed-off-by: José Bollo --- include/afb/afb-event-itf.h | 84 +++++++++++++++++++++++++++++++++++++++++++++ include/afb/afb-plugin.h | 17 +++++++-- include/afb/afb-req-itf.h | 28 +++++++++++++++ 3 files changed, 127 insertions(+), 2 deletions(-) create mode 100644 include/afb/afb-event-itf.h (limited to 'include/afb') diff --git a/include/afb/afb-event-itf.h b/include/afb/afb-event-itf.h new file mode 100644 index 00000000..47ffa387 --- /dev/null +++ b/include/afb/afb-event-itf.h @@ -0,0 +1,84 @@ +/* + * Copyright (C) 2016 "IoT.bzh" + * Author: José Bollo + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#pragma once + +/* avoid inclusion of */ +struct json_object; + +/* + * Interface for handling requests. + * It records the functions to be called for the request. + * Don't use this structure directly. + * Use the helper functions documented below. + */ +struct afb_event_itf { + /* CAUTION: respect the order, add at the end */ + + int (*broadcast)(void *closure, struct json_object *obj); + int (*push)(void *closure, struct json_object *obj); + void (*drop)(void *closure); +}; + +/* + * Describes the request by plugins from afb-daemon + */ +struct afb_event { + const struct afb_event_itf *itf; /* the interface to use */ + void *closure; /* the closure argument for functions of 'itf' */ +}; + +/* + * Broadcasts widely the 'event' with the data 'object'. + * 'object' can be NULL. + * + * For conveniency, 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. + * + * Returns the count of clients that received the event. + */ +static inline int afb_event_broadcast(struct afb_event event, struct json_object *object) +{ + return event.itf->broadcast(event.closure, object); +} + +/* + * Pushes the 'event' with the data 'object' to its obeservers. + * 'object' can be NULL. + * + * For conveniency, 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. + * + * Returns the count of clients that received the event. + */ +static inline int afb_event_push(struct afb_event event, struct json_object *object) +{ + return event.itf->push(event.closure, object); +} + +/* + * Drops the data associated to the event + * After calling this function, the event + * MUST NOT BE USED ANYMORE. + */ +static inline void afb_event_drop(struct afb_event event) +{ + event.itf->drop(event.closure); +} + diff --git a/include/afb/afb-plugin.h b/include/afb/afb-plugin.h index 1eb3475b..85e8de7e 100644 --- a/include/afb/afb-plugin.h +++ b/include/afb/afb-plugin.h @@ -38,6 +38,7 @@ * Some function of the library are exported to afb-daemon. */ +#include #include /* @@ -140,11 +141,12 @@ struct sd_bus; * Definition of the facilities provided by the daemon. */ struct afb_daemon_itf { - void (*event_broadcast)(void *closure, const char *name, struct json_object *object); /* broadcasts evant 'name' with 'object' */ + int (*event_broadcast)(void *closure, const char *name, struct json_object *object); /* broadcasts evant 'name' with 'object' */ struct sd_event *(*get_event_loop)(void *closure); /* gets the common systemd's event loop */ struct sd_bus *(*get_user_bus)(void *closure); /* gets the common systemd's user d-bus */ struct sd_bus *(*get_system_bus)(void *closure); /* gets the common systemd's system d-bus */ void (*vverbose)(void*closure, int level, const char *file, int line, const char *fmt, va_list args); + struct afb_event (*event_make)(void *closure, const char *name); /* creates an event of 'name' */ }; /* @@ -206,12 +208,23 @@ static inline struct sd_bus *afb_daemon_get_system_bus(struct afb_daemon daemon) * For conveniency, 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. + * + * Returns the count of clients that received the event. */ -static inline void afb_daemon_broadcast_event(struct afb_daemon daemon, const char *name, struct json_object *object) +static inline int afb_daemon_broadcast_event(struct afb_daemon daemon, const char *name, struct json_object *object) { return daemon.itf->event_broadcast(daemon.closure, name, object); } +/* + * Creates an event of 'name' and returns it. + * 'daemon' MUST be the daemon given in interface when activating the plugin. + */ +static inline struct afb_event afb_daemon_make_event(struct afb_daemon daemon, const char *name) +{ + return daemon.itf->event_make(daemon.closure, name); +} + /* * Send a message described by 'fmt' and following parameters * to the journal for the verbosity 'level'. diff --git a/include/afb/afb-req-itf.h b/include/afb/afb-req-itf.h index f4fab551..2b3bc467 100644 --- a/include/afb/afb-req-itf.h +++ b/include/afb/afb-req-itf.h @@ -25,6 +25,8 @@ #include #include +#include + /* avoid inclusion of */ struct json_object; @@ -65,6 +67,9 @@ struct afb_req_itf { void (*session_close)(void *closure); int (*session_set_LOA)(void *closure, unsigned level); + + int (*subscribe)(void *closure, struct afb_event event); + int (*unsubscribe)(void *closure, struct afb_event event); }; /* @@ -315,6 +320,29 @@ static inline struct afb_req afb_req_unstore(struct afb_req *req) return result; } +/* + * Establishes for the client link identified by 'req' a subscription + * to the 'event'. + * Returns 0 in case of successful subscription or -1 in case of error. + */ +static inline int afb_req_subscribe(struct afb_req req, struct afb_event event) +{ + return req.itf->subscribe(req.closure, event); +} + +/* + * Revokes the subscription established to the 'event' for the client + * link identified by 'req'. + * Returns 0 in case of successful subscription or -1 in case of error. + */ +static inline int afb_req_unsubscribe(struct afb_req req, struct afb_event event) +{ + return req.itf->unsubscribe(req.closure, event); +} + + + + /* internal use */ static inline const char *afb_req_raw(struct afb_req req, size_t *size) { -- cgit 1.2.3-korg