<h1>HOWTO WRITE a PLUGIN for AFB-DAEMON</h1>
<pre><code>version: 1
-Date: 27 mai 2016
+Date: 29 mai 2016
Author: José Bollo
</code></pre>
<li><a href="#Summary">Summary</a>
<ul>
<li><a href="#Nature.of.a.plugin">Nature of a plugin</a></li>
- <li><a href="#Kinds.of.plugins">Kinds of plugins</a>
+ <li><a href="#Class.of.plugins">Class of plugins</a>
<ul>
- <li><a href="#Application.plugins">Application plugins</a></li>
- <li><a href="#Service.plugins">Service plugins</a></li>
+ <li><a href="#Application-plugins">Application-plugins</a></li>
+ <li><a href="#Service-plugins">Service-plugins</a></li>
</ul>
</li>
- <li><a href="#Live.cycle.of.a.plugin.within.afb-daemon">Live cycle of a plugin within afb-daemon</a></li>
- <li><a href="#Content.of.a.plugin">Content of a plugin</a>
+ <li><a href="#Live.cycle.of.plugins.within.afb-daemon">Live cycle of plugins within afb-daemon</a></li>
+ <li><a href="#Plugin.Contend">Plugin Contend</a>
<ul>
<li><a href="#The.name.of.the.plugin">The name of the plugin</a></li>
<li><a href="#Names.of.verbs">Names of verbs</a></li>
<a name="Summary"></a>
<h2>Summary</h2>
-<p>The binder afb-daemon serves files through
-the HTTP protocol and offers access to API’s through
+<p>The binder afb-daemon serves files through HTTP protocol
+and offers to developers the capability to expose application APIs through
HTTP or WebSocket protocol.</p>
-<p>The plugins are used to add API’s to afb-daemon.
+<p>Binder plugins are used to add API to afb-daemon.
This part describes how to write a plugin for afb-daemon.
Excepting this summary, this part is intended to be read
-by developpers.</p>
+by developers.</p>
-<p>Before going into details, through a tiny example,
-a short overview plugins basis is needed.</p>
+<p>Before moving further through an example, here after
+a short overview of binder plugins fundamentals.</p>
<a name="Nature.of.a.plugin"></a>
<h3>Nature of a plugin</h3>
-<p>A plugin is a separate piece of code made of a shared library.
-The plugin is loaded and activated by afb-daemon when afb-daemon
-starts.</p>
+<p>A plugin is an independent piece of software, self contain and expose as a dynamically loadable library.
+A plugin is loaded by afb-daemon that exposes contained API dynamically at runtime.</p>
-<p>Technically, a plugin is not linked to any library of afb-daemon.</p>
+<p>Technically, a binder plugins does not reference and is not linked with any library from afb-daemon.</p>
-<a name="Kinds.of.plugins"></a>
-<h3>Kinds of plugins</h3>
+<a name="Class.of.plugins"></a>
+<h3>Class of plugins</h3>
-<p>There is two kinds of plugins: application plugins and service
-plugins.</p>
+<p>Application binder supports two kinds of plugins: application plugins and service
+plugins. Technically both class of plugin are equivalent and coding API is shared. Only sharing mode and security context diverge.</p>
-<a name="Application.plugins"></a>
-<h4>Application plugins</h4>
+<a name="Application-plugins"></a>
+<h4>Application-plugins</h4>
-<p>Application plugins are intended to be instanciated for each
-application: when an application using that plugin is started,
-its binder starts a new instance of the plugin.</p>
+<p>Application-plugins implements the glue in between application’s UI and services. Every AGL application
+has a corresponding binder that typically activates one or many plugins to interface the application logic with lower platform services.
+When an application is started by AGL application framework, a dedicate binder is started that loads/activates application plugin(s).
+The API expose by application-plugin are executed within corresponding application security context.</p>
-<p>It means that the application plugins mainly have only one
-context to manage for one client.</p>
+<p>Application plugins generally handle a unique context for a unique client. As the application framework start
+a dedicated instance of afb_daemon for each AGL application, if a given plugin is used within multiple application each of those
+application get a new and private instance of this “shared” plugin.</p>
-<a name="Service.plugins"></a>
-<h4>Service plugins</h4>
+<a name="Service-plugins"></a>
+<h4>Service-plugins</h4>
-<p>Service plugins are intended to be instanciated only one time
-only and connected to many clients.</p>
+<p>Service-plugins enable API activation within corresponding service security context and not within calling application context.
+Service-plugins are intended to run as a unique instance that is shared in between multiple clients.</p>
-<p>So either it does not manage context at all or otherwise,
-if it manages context, it should be able to manage one context
-per client.</p>
+<p>Service-plugins can either be stateless or manage client context. When managing context each client get a private context.</p>
-<p>In details, it may be useful to have service plugins at a user
-level.</p>
+<p>Sharing may either be global to the platform (ie: GPS service) or dedicated to a given user (ie: preference management)</p>
-<a name="Live.cycle.of.a.plugin.within.afb-daemon"></a>
-<h3>Live cycle of a plugin within afb-daemon</h3>
+<a name="Live.cycle.of.plugins.within.afb-daemon"></a>
+<h3>Live cycle of plugins within afb-daemon</h3>
-<p>The plugins are loaded and activated when afb-daemon starts.</p>
+<p>Application and service plugins are loaded and activated each time a new afb-daemon is started.</p>
-<p>At start, the plugin initialise itself.
-If it fails to initialise then afb-daemon stops.</p>
+<p>At launch time, every loaded plugin initialise itself.
+If a single plugin initialisation fail corresponding instance of afb-daemon self aborts.</p>
-<p>Conversely, if it success to initialize, it must declare
-a name, that must be unique, and a list of API’s verbs.</p>
+<p>Conversely, when plugin initialisation succeeds, it should register
+its unique name and the list of API verbs it exposes.</p>
-<p>When initialized, the functions implementing the API’s verbs
-of the plugin are activated on call.</p>
+<p>When initialised, on request from clients plugin’s function corresponding to expose API verbs
+are activated by the afb-daemon instance attached to the application or service.</p>
-<p>At the end, nothing special is done by afb-daemon.
-Consequently, developpers of plugins should use ‘atexit’
-or ‘on_exit’ during initialisation if they need to
-perform specific actions when stopping.</p>
+<p>At exit time, no special action is enforced by afb-daemon. When a specific actions is required at afb-daemon stop,
+developers should use ‘atexit/on_exit’ during plugin initialisation sequence to register a custom exit function.</p>
-<a name="Content.of.a.plugin"></a>
-<h3>Content of a plugin</h3>
+<a name="Plugin.Contend"></a>
+<h3>Plugin Contend</h3>
-<p>For afb-daemon, a plugin contains 2 different
-things: names and functions.</p>
+<p>Afb-daemon’s plugin register two classes of objects: names and functions.</p>
-<p>There is two kind of names:
- - the name of the plugin,
- - the names of the verbs.</p>
+<p>Plugins declare categories of names:
+ - A unique plugin name,
+ - Multiple API verb’s names.</p>
-<p>There is two kind of functions:
- - the initialisation function
- - functions implementing verbs</p>
+<p>Plugins declare two categories of functions:
+ - initialisation function
+ - API functions implementing verbs</p>
-<p>Afb-daemon translates the name of the method that is
-invoked to a pair of API and verb names. For example,
-the method named <strong>foo/bar</strong> translated to the API
-name <strong>foo</strong> and the verb name <strong>bar</strong>.
-To serve it, afb-daemon search the plugin that record
-the name <strong>foo</strong> and if it also recorded the verb <strong>bar</strong>,
-it calls the implementation function declared for this verb.</p>
+<p>Afb-daemon parses URI requests to extract plugin name and API verb.
+As an example, URI <strong>foo/bar</strong> translates to API verb named <strong>bar</strong> within plugin named <strong>foo</strong>.
+To serve such a request, afb-daemon looks for an active plugin named <strong>foo</strong> and then within this plugin for an API verb named <strong>bar</strong>.
+When find afb-daemon calls corresponding function with attached parameter if any.</p>
-<p>Afb-daemon make no distinction between lower case
-and upper case when searching for a method.
-Thus, The names <strong>TicTacToe/Board</strong> and <strong>tictactoe/borad</strong>
-are equals.</p>
+<p>Afb-daemon ignores letter case when parsing URI. Thus <strong>TicTacToe/Board</strong> and <strong>tictactoe/board</strong> are equivalent.</p>
<a name="The.name.of.the.plugin"></a>
<h4>The name of the plugin</h4>
<p>The names of the verbs are not checked.</p>
<p>However, the validity rules for verb’s names are the
-same as for API’s names except that the dot (.) character
+same as for API names except that the dot (.) character
is forbidden.</p>
<p>Afb-daemon make no distinction between lower case
struct json_object;
+/*
+ * Interface for callback functions.
+ * The received closure is the closure passed when creating the afb_wsj1
+ * socket using afb_wsj1_create.
+ */
struct afb_wsj1_itf {
+ /*
+ * This function is called on hangup.
+ * Receives the 'closure' and the handle 'wsj1'
+ */
void (*on_hangup)(void *closure, struct afb_wsj1 *wsj1);
+
+ /*
+ * This function is called on incoming call.
+ * Receives the 'closure'
+ */
void (*on_call)(void *closure, const char *api, const char *verb, struct afb_wsj1_msg *msg);
+
+ /*
+ * This function is called on incoming event
+ */
void (*on_event)(void *closure, const char *event, struct afb_wsj1_msg *msg);
};
+/*
+ * Creates the afb_wsj1 socket connected to the file descriptor 'fd'
+ * and having the callback interface defined by 'itf' for the 'closure'.
+ * Returns the created wsj1 websocket or NULL in case of error.
+ */
extern struct afb_wsj1 *afb_wsj1_create(int fd, struct afb_wsj1_itf *itf, void *closure);
+/*
+ * Increases by one the count of reference to 'wsj1'
+ */
extern void afb_wsj1_addref(struct afb_wsj1 *wsj1);
+
+/*
+ * Decreases by one the count of reference to 'wsj1'
+ * and if it falls to zero releases the used resources
+ * and free the memory
+ */
extern void afb_wsj1_unref(struct afb_wsj1 *wsj1);
+/*
+ * Sends on 'wsj1' the event of name 'event' with the
+ * data 'object'. If not NULL, 'object' should be a valid
+ * JSON string.
+ * Return 0 in case of success. Otherwise, returns -1 and set errno.
+ */
extern int afb_wsj1_send_event_s(struct afb_wsj1 *wsj1, const char *event, const char *object);
+
+/*
+ * Sends on 'wsj1' the event of name 'event' with the
+ * data 'object'. 'object' can be NULL.
+ * Return 0 in case of success. Otherwise, returns -1 and set errno.
+ */
extern int afb_wsj1_send_event_j(struct afb_wsj1 *wsj1, const char *event, struct json_object *object);
+/*
+ * Sends on 'wsj1' a call to the method of 'api'/'verb' with arguments
+ * given by 'object'. If not NULL, 'object' should be a valid JSON string.
+ * On receiving the reply, the function 'on_reply' is called with 'closure'
+ * as its first argument and the message of the reply.
+ * Return 0 in case of success. Otherwise, returns -1 and set errno.
+ */
extern int afb_wsj1_call_s(struct afb_wsj1 *wsj1, const char *api, const char *verb, const char *object, void (*on_reply)(void *closure, struct afb_wsj1_msg *msg), void *closure);
+
+/*
+ * Sends on 'wsj1' a call to the method of 'api'/'verb' with arguments
+ * given by 'object'. 'object' can be NULL.
+ * On receiving the reply, the function 'on_reply' is called with 'closure'
+ * as its first argument and the message of the reply.
+ * Return 0 in case of success. Otherwise, returns -1 and set errno.
+ */
extern int afb_wsj1_call_j(struct afb_wsj1 *wsj1, const char *api, const char *verb, struct json_object *object, void (*on_reply)(void *closure, struct afb_wsj1_msg *msg), void *closure);
+/*
+ * Sends for message 'msg' the OK reply with the 'object' and, if not NULL, the token.
+ * If not NULL, 'object' should be a valid JSON string.
+ * Return 0 in case of success. Otherwise, returns -1 and set errno.
+ */
extern int afb_wsj1_reply_ok_s(struct afb_wsj1_msg *msg, const char *object, const char *token);
+
+/*
+ * Sends for message 'msg' the OK reply with the 'object' and, if not NULL, the token.
+ * 'object' can be NULL.
+ * Return 0 in case of success. Otherwise, returns -1 and set errno.
+ */
extern int afb_wsj1_reply_ok_j(struct afb_wsj1_msg *msg, struct json_object *object, const char *token);
+/*
+ * Sends for message 'msg' the ERROR reply with the 'object' and, if not NULL, the token.
+ * If not NULL, 'object' should be a valid JSON string.
+ * Return 0 in case of success. Otherwise, returns -1 and set errno.
+ */
extern int afb_wsj1_reply_error_s(struct afb_wsj1_msg *msg, const char *object, const char *token);
+
+/*
+ * Sends for message 'msg' the ERROR reply with the 'object' and, if not NULL, the token.
+ * 'object' can be NULL.
+ * Return 0 in case of success. Otherwise, returns -1 and set errno.
+ */
extern int afb_wsj1_reply_error_j(struct afb_wsj1_msg *msg, struct json_object *object, const char *token);
+/*
+ * Increases by one the count of reference to 'msg'.
+ * Should be called if callbacks stores the message.
+ */
extern void afb_wsj1_msg_addref(struct afb_wsj1_msg *msg);
+
+/*
+ * Decreases by one the count of reference to 'msg'.
+ * and if it falls to zero releases the used resources
+ * and free the memory.
+ * Should be called if 'afb_wsj1_msg_addref' was called.
+ */
extern void afb_wsj1_msg_unref(struct afb_wsj1_msg *msg);
+/*
+ * Returns 1 if 'msg' is for a CALL
+ * Otherwise returns 0.
+ */
extern int afb_wsj1_msg_is_call(struct afb_wsj1_msg *msg);
+
+/*
+ * Returns 1 if 'msg' is for a REPLY of any kind
+ * Otherwise returns 0.
+ */
extern int afb_wsj1_msg_is_reply(struct afb_wsj1_msg *msg);
+
+/*
+ * Returns 1 if 'msg' is for a REPLY OK
+ * Otherwise returns 0.
+ */
extern int afb_wsj1_msg_is_reply_ok(struct afb_wsj1_msg *msg);
+
+/*
+ * Returns 1 if 'msg' is for a REPLY ERROR
+ * Otherwise returns 0.
+ */
extern int afb_wsj1_msg_is_reply_error(struct afb_wsj1_msg *msg);
+
+/*
+ * Returns 1 if 'msg' is for an EVENT
+ * Otherwise returns 0.
+ */
extern int afb_wsj1_msg_is_event(struct afb_wsj1_msg *msg);
+/*
+ * Returns the api of the call for 'msg'
+ * Returns NULL if 'msg' is not for a CALL
+ */
extern const char *afb_wsj1_msg_api(struct afb_wsj1_msg *msg);
+
+/*
+ * Returns the verb call for 'msg'
+ * Returns NULL if 'msg' is not for a CALL
+ */
extern const char *afb_wsj1_msg_verb(struct afb_wsj1_msg *msg);
+
+/*
+ * Returns the event name for 'msg'
+ * Returns NULL if 'msg' is not for an EVENT
+ */
extern const char *afb_wsj1_msg_event(struct afb_wsj1_msg *msg);
+
+/*
+ * Returns the token sent with 'msg' or NULL when no token was sent.
+ */
extern const char *afb_wsj1_msg_token(struct afb_wsj1_msg *msg);
+
+/*
+ * Returns the wsj1 of 'msg'
+ */
extern struct afb_wsj1 *afb_wsj1_msg_wsj1(struct afb_wsj1_msg *msg);
+/*
+ * Returns the string representation of the object received with 'msg'
+ */
extern const char *afb_wsj1_msg_object_s(struct afb_wsj1_msg *msg);
+
+/*
+ * Returns the object received with 'msg'
+ */
extern struct json_object *afb_wsj1_msg_object_j(struct afb_wsj1_msg *msg);
Code Review / src / app-framework-binder.git / commitdiff