doc/writing-afb-plugins.html

   1 <html>
   2 <head>
   3   <link rel="stylesheet" type="text/css" href="doc.css">
   4   <meta charset="UTF-8">
   5 </head>
   6 <body>
   7 <a name="HOWTO.WRITE.a.PLUGIN.for.AFB-DAEMON"></a>
   8 <h1>HOWTO WRITE a PLUGIN for AFB-DAEMON</h1>
   9
  10 <pre><code>version: 1
  11 Date:    24 mai 2016
  12 Author:  José Bollo
  13 </code></pre>
  14
  15 <p><ul>
  16  <li><a href="#HOWTO.WRITE.a.PLUGIN.for.AFB-DAEMON">HOWTO WRITE a PLUGIN for AFB-DAEMON</a>
  17  <ul>
  18   <li><a href="#Summary">Summary</a>
  19   <ul>
  20    <li><a href="#Nature.of.a.plugin">Nature of a plugin</a></li>
  21    <li><a href="#Live.cycle.of.a.plugin.within.afb-daemon">Live cycle of a plugin within afb-daemon</a></li>
  22    <li><a href="#Content.of.a.plugin">Content of a plugin</a>
  23    <ul>
  24     <li><a href="#The.name.of.the.plugin">The name of the plugin</a></li>
  25     <li><a href="#Names.of.verbs">Names of verbs</a></li>
  26     <li><a href="#The.initialisation.function">The initialisation function</a></li>
  27     <li><a href="#Functions.implementing.verbs">Functions implementing verbs</a>
  28 </li>
  29    </ul>
  30    </li>
  31   </ul>
  32   </li>
  33   <li><a href="#The.Tic-Tac-Toe.example">The Tic-Tac-Toe example</a></li>
  34   <li><a href="#Choosing.names">Choosing names</a>
  35   <ul>
  36    <li><a href="#Names.for.API..plugin.">Names for API (plugin)</a></li>
  37    <li><a href="#Names.for.verbs">Names for verbs</a></li>
  38    <li><a href="#Names.for.arguments">Names for arguments</a></li>
  39    <li><a href="#Forging.names.widely.available">Forging names widely available</a></li>
  40   </ul>
  41   </li>
  42   <li><a href="#Options.to.set.when.compiling.plugins">Options to set when compiling plugins</a></li>
  43   <li><a href="#Header.files.to.include">Header files to include</a></li>
  44   <li><a href="#Writing.a.synchronous.verb.implementation">Writing a synchronous verb implementation</a>
  45   <ul>
  46    <li><a href="#The.incoming.request">The incoming request</a></li>
  47    <li><a href="#Associating.an.object.to.the.session.for.the.plugin">Associating an object to the session for the plugin</a></li>
  48    <li><a href="#Sending.the.reply.to.a.request">Sending the reply to a request</a></li>
  49   </ul>
  50   </li>
  51   <li><a href="#Getting.argument.of.invocation">Getting argument of invocation</a></li>
  52   <li><a href="#How.to.build.a.plugin">How to build a plugin</a></li>
  53  </ul>
  54  </li>
  55 </ul></p>
  56
  57 <a name="Summary"></a>
  58 <h2>Summary</h2>
  59
  60 <p>The binder afb-daemon serves files through
  61 the HTTP protocol and offers access to API&rsquo;s through
  62 HTTP or WebSocket protocol.</p>
  63
  64 <p>The plugins are used to add API&rsquo;s to afb-daemon.
  65 This part describes how to write a plugin for afb-daemon.
  66 Excepting this summary, this part is intended to be read
  67 by developpers.</p>
  68
  69 <p>Before going into details, through a tiny example,
  70 a short overview plugins basis is needed.</p>
  71
  72 <a name="Nature.of.a.plugin"></a>
  73 <h3>Nature of a plugin</h3>
  74
  75 <p>A plugin is a separate piece of code made of a shared library.
  76 The plugin is loaded and activated by afb-daemon when afb-daemon
  77 starts.</p>
  78
  79 <p>Technically, a plugin is not linked to any library of afb-daemon.</p>
  80
  81 <a name="Live.cycle.of.a.plugin.within.afb-daemon"></a>
  82 <h3>Live cycle of a plugin within afb-daemon</h3>
  83
  84 <p>The plugins are loaded and activated when afb-daemon starts.</p>
  85
  86 <p>At start, the plugin initialise itself.
  87 If it fails to initialise then afb-daemon stops.</p>
  88
  89 <p>Conversely, if it success to initialize, it must declare
  90 a name, that must be unique, and a list of API&rsquo;s verbs.</p>
  91
  92 <p>When initialized, the functions implementing the API&rsquo;s verbs
  93 of the plugin are activated on call.</p>
  94
  95 <p>At the end, nothing special is done by afb-daemon.
  96 Consequently, developpers of plugins should use &lsquo;atexit&rsquo;
  97 or &lsquo;on_exit&rsquo; during initialisation if they need to
  98 perform specific actions when stopping.</p>
  99
 100 <a name="Content.of.a.plugin"></a>
 101 <h3>Content of a plugin</h3>
 102
 103 <p>For afb-daemon, a plugin contains 2 different
 104 things: names and functions.</p>
 105
 106 <p>There is two kind of names:
 107  - the name of the plugin,
 108  - the names of the verbs.</p>
 109
 110 <p>There is two kind of functions:
 111  - the initialisation function
 112  - functions implementing verbs</p>
 113
 114 <p>Afb-daemon translates the name of the method that is
 115 invoked to a pair of API and verb names. For example,
 116 the method named <strong>foo/bar</strong> translated to the API
 117 name <strong>foo</strong> and the verb name <strong>bar</strong>.
 118 To serve it, afb-daemon search the plugin that record
 119 the name <strong>foo</strong> and if it also recorded the verb <strong>bar</strong>,
 120 it calls the implementation function declared for this verb.</p>
 121
 122 <p>Afb-daemon make no distinction between lower case
 123 and upper case when searching for a method.
 124 Thus, The names <strong>TicTacToe/Board</strong> and <strong>tictactoe/borad</strong>
 125 are equals.</p>
 126
 127 <a name="The.name.of.the.plugin"></a>
 128 <h4>The name of the plugin</h4>
 129
 130 <p>The name of the plugin is also known as the name
 131 of the API that defines the plugin.</p>
 132
 133 <p>This name is also known as the prefix.</p>
 134
 135 <p>The name of a plugin MUST be unique within afb-daemon.</p>
 136
 137 <p>For example, when a client of afb-daemon
 138 calls a method named <strong>foo/bar</strong>. Afb-daemon
 139 extracts the prefix <strong>foo</strong> and the suffix <strong>bar</strong>.
 140 <strong>foo</strong> is the API name and must match a plugin name,
 141 the plugin that implements the verb <strong>bar</strong>.</p>
 142
 143 <a name="Names.of.verbs"></a>
 144 <h4>Names of verbs</h4>
 145
 146 <p>Each plugin exposes a set of verbs that can be called
 147 by client of afb-daemon.</p>
 148
 149 <p>The name of a verb MUST be unique within a plugin.</p>
 150
 151 <p>Plugins link verbs to functions that are called
 152 when clients emit requests for that verb.</p>
 153
 154 <p>For example, when a client of afb-daemon
 155 calls a method named <strong>foo/bar</strong>.</p>
 156
 157 <a name="The.initialisation.function"></a>
 158 <h4>The initialisation function</h4>
 159
 160 <p>The initialisation function serves several purposes.</p>
 161
 162 <ol>
 163 <li><p>It allows afb-daemon to check the version
 164 of the plugin using the name of the initialisation
 165 functions that it found. Currently, the initialisation
 166 function is named <strong>pluginAfbV1Register</strong>. It identifies
 167 the first version of plugins.</p></li>
 168 <li><p>It allows the plugin to initialise itself.</p></li>
 169 <li><p>It serves to the plugin to declare names, descriptions,
 170 requirements and implmentations of the verbs that it exposes.</p></li>
 171 </ol>
 172
 173
 174 <a name="Functions.implementing.verbs"></a>
 175 <h4>Functions implementing verbs</h4>
 176
 177 <p>When a method is called, afb-daemon constructs a request
 178 object and pass it to the implementation function for verb
 179 within the plugin of the API.</p>
 180
 181 <p>An implementation function receives a request object that
 182 is used to get arguments of the request, to send
 183 answer, to store session data.</p>
 184
 185 <p>A plugin MUST send an answer to the request.</p>
 186
 187 <p>But it is not mandatory to send the answer
 188 before to return from the implementing function.
 189 This behaviour is important for implementing
 190 asynchronous actions.</p>
 191
 192 <p>Implementation functions that always reply to the request
 193 before returning are named <em>synchronous implementations</em>.
 194 Those that don&rsquo;t always reply to the request before
 195 returning are named <em>asynchronous implementations</em>.</p>
 196
 197 <p>Asynchronous implementations typically initiate an
 198 asynchronous action and record to send the reply
 199 on completion of this action.</p>
 200
 201 <a name="The.Tic-Tac-Toe.example"></a>
 202 <h2>The Tic-Tac-Toe example</h2>
 203
 204 <p>This part explains how to write an afb-plugin.
 205 For the sake of being practical we will use many
 206 examples from the tic-tac-toe example.
 207 This plugin example is in <em>plugins/samples/tic-tac-toe.c</em>.</p>
 208
 209 <p>This plugin is named <strong><em>tictactoe</em></strong>.</p>
 210
 211 <a name="Choosing.names"></a>
 212 <h2>Choosing names</h2>
 213
 214 <p>The designer of a plugin must defines names for its plugin
 215 (or its API) and for the verbs of its API. He also
 216 must defines names for arguments given by name.</p>
 217
 218 <p>While forging names, the designer should take into account
 219 the rules for making valid names and some rules that make
 220 the names easy to use across plaforms.</p>
 221
 222 <p>The names and strings used ALL are UTF-8 encoded.</p>
 223
 224 <a name="Names.for.API..plugin."></a>
 225 <h3>Names for API (plugin)</h3>
 226
 227 <p>The names of the API are checked.
 228 All characters are authorised except:</p>
 229
 230 <ul>
 231 <li>the control characters (\u0000 .. \u001f)</li>
 232 <li>the characters of the set { &lsquo; &rsquo;, &lsquo;&ldquo;&rsquo;, &lsquo;#&rsquo;, &lsquo;%&rsquo;, &lsquo;&amp;&rsquo;,
 233 &lsquo;&rsquo;&lsquo;, &rsquo;/&lsquo;, &rsquo;?&lsquo;, &rsquo;`&lsquo;, &rsquo;\x7f' }</li>
 234 </ul>
 235
 236
 237 <p>In other words the set of forbidden characters is
 238 { \u0000..\u0020, \u0022, \u0023, \u0025..\u0027,
 239   \u002f, \u003f, \u0060, \u007f }.</p>
 240
 241 <p>Afb-daemon make no distinction between lower case
 242 and upper case when searching for an API by its name.</p>
 243
 244 <a name="Names.for.verbs"></a>
 245 <h3>Names for verbs</h3>
 246
 247 <p>The names of the verbs are not checked.</p>
 248
 249 <p>However, the validity rules for verb&rsquo;s names are the
 250 same as for API&rsquo;s names except that the dot (.) character
 251 is forbidden.</p>
 252
 253 <p>Afb-daemon make no distinction between lower case
 254 and upper case when searching for an API by its name.</p>
 255
 256 <a name="Names.for.arguments"></a>
 257 <h3>Names for arguments</h3>
 258
 259 <p>The names for arguments are not restricted and can be
 260 anything.</p>
 261
 262 <p>The arguments are searched with the case sensitive
 263 string comparison. Thus the names &ldquo;index&rdquo; and &ldquo;Index&rdquo;
 264 are not the same.</p>
 265
 266 <a name="Forging.names.widely.available"></a>
 267 <h3>Forging names widely available</h3>
 268
 269 <p>The key names of javascript object can be almost
 270 anything using the arrayed notation:</p>
 271
 272 <pre><code>object[key] = value
 273 </code></pre>
 274
 275 <p>That is not the case with the dot notation:</p>
 276
 277 <pre><code>object.key = value
 278 </code></pre>
 279
 280 <p>Using the dot notation, the key must be a valid javascript
 281 identifier.</p>
 282
 283 <p>For this reason, the chosen names should better be
 284 valid javascript identifier.</p>
 285
 286 <p>It is also a good practice, even for arguments, to not
 287 rely on the case sensitivity and to avoid the use of
 288 names different only by the case.</p>
 289
 290 <a name="Options.to.set.when.compiling.plugins"></a>
 291 <h2>Options to set when compiling plugins</h2>
 292
 293 <p>Afb-daemon provides a configuration file for <em>pkg-config</em>.
 294 Typing the command</p>
 295
 296 <pre><code>pkg-config --cflags afb-daemon
 297 </code></pre>
 298
 299 <p>will print the flags to use for compiling, like this:</p>
 300
 301 <pre><code>$ pkg-config --cflags afb-daemon
 302 -I/opt/local/include -I/usr/include/json-c
 303 </code></pre>
 304
 305 <p>For linking, you should use</p>
 306
 307 <pre><code>$ pkg-config --libs afb-daemon
 308 -ljson-c
 309 </code></pre>
 310
 311 <p>As you see, afb-daemon automatically includes dependency to json-c.
 312 This is done through the <strong>Requires</strong> keyword of pkg-config.</p>
 313
 314 <p>If this behaviour is a problem, let us know.</p>
 315
 316 <a name="Header.files.to.include"></a>
 317 <h2>Header files to include</h2>
 318
 319 <p>The plugin <em>tictactoe</em> has the following lines for its includes:</p>
 320
 321 <pre><code>#define _GNU_SOURCE
 322 #include &lt;stdio.h&gt;
 323 #include &lt;string.h&gt;
 324 #include &lt;json-c/json.h&gt;
 325 #include &lt;afb/afb-plugin.h&gt;
 326 </code></pre>
 327
 328 <p>The header <em>afb/afb-plugin.h</em> includes all the features that a plugin
 329 needs except two foreign header that must be included by the plugin
 330 if it needs it:</p>
 331
 332 <ul>
 333 <li><em>json-c/json.h</em>: this header must be include to handle json objects;</li>
 334 <li><em>systemd/sd-event.h</em>: this must be include to access the main loop;</li>
 335 <li><em>systemd/sd-bus.h</em>: this may be include to use dbus connections.</li>
 336 </ul>
 337
 338
 339 <p>The <em>tictactoe</em> plugin does not use systemd features so it is not included.</p>
 340
 341 <p>When including <em>afb/afb-plugin.h</em>, the macro <strong>_GNU_SOURCE</strong> must be
 342 defined.</p>
 343
 344 <a name="Writing.a.synchronous.verb.implementation"></a>
 345 <h2>Writing a synchronous verb implementation</h2>
 346
 347 <p>The verb <strong>tictactoe/board</strong> is a synchronous implementation.
 348 Here is its listing:</p>
 349
 350 <pre><code>/*
 351  * get the board
 352  */
 353 static void board(struct afb_req req)
 354 {
 355     struct board *board;
 356     struct json_object *description;
 357
 358     /* retrieves the context for the session */
 359     board = board_of_req(req);
 360     INFO(afbitf, "method 'board' called for boardid %d", board-&gt;id);
 361
 362     /* describe the board */
 363     description = describe(board);
 364
 365     /* send the board's description */
 366     afb_req_success(req, description, NULL);
 367 }
 368 </code></pre>
 369
 370 <p>This examples show many aspects of writing a synchronous
 371 verb implementation.</p>
 372
 373 <a name="The.incoming.request"></a>
 374 <h3>The incoming request</h3>
 375
 376 <p>For any implementation,  the request is received by a structure of type
 377 <strong>struct afb_req</strong>.</p>
 378
 379 <p><strong><em>Important: note that this is a PLAIN structure, not a pointer to a structure.</em></strong></p>
 380
 381 <p>This structure, here named <em>req</em>, is used</p>
 382
 383 <p><em>req</em> is used to get arguments of the request, to send
 384 answer, to store session data.</p>
 385
 386 <p>This object and its interface is defined and documented
 387 in the file names <em>afb/afb-req-itf.h</em></p>
 388
 389 <p>The above example uses 2 times the request object <em>req</em>.</p>
 390
 391 <p>The first time, it is used for retrieving the board attached to
 392 the session of the request.</p>
 393
 394 <p>The second time, it is used to send the reply: an object that
 395 describes the current board.</p>
 396
 397 <a name="Associating.an.object.to.the.session.for.the.plugin"></a>
 398 <h3>Associating an object to the session for the plugin</h3>
 399
 400 <p>When the plugin <em>tic-tac-toe</em> receives a request, it musts regain
 401 the board that describes the game associated to the session.</p>
 402
 403 <p>For a plugin, having data associated to a session is a common case.
 404 This data is called the context of the plugin for the session.
 405 For the plugin <em>tic-tac-toe</em>, the context is the board.</p>
 406
 407 <p>The requests <em>afb_req</em> offer four functions for
 408 storing and retrieving the context associated to the session.</p>
 409
 410 <p>These functions are:</p>
 411
 412 <ul>
 413 <li><p><strong>afb_req_context_get</strong>:
 414 retrieves the context data stored for the plugin.</p></li>
 415 <li><p><strong>afb_req_context_set</strong>:
 416 store the context data of the plugin.</p></li>
 417 <li><p><strong>afb_req_context</strong>:
 418 retrieves the context data of the plugin,
 419 if needed, creates the context and store it.</p></li>
 420 <li><p><strong>afb_req_context_clear</strong>:
 421 reset the stored data.</p></li>
 422 </ul>
 423
 424
 425 <p>The plugin <em>tictactoe</em> use a convenient function to retrieve
 426 its context: the board. This function is <em>board_of_req</em>:</p>
 427
 428 <pre><code>/*
 429  * retrieves the board of the request
 430  */
 431 static inline struct board *board_of_req(struct afb_req req)
 432 {
 433     return afb_req_context(req, (void*)get_new_board, (void*)release_board);
 434 }
 435 </code></pre>
 436
 437 <p>This function is very simple because it merely wraps
 438 a call to the function <strong>afb_req_context</strong>, providing
 439 all needed arguments.
 440 The casts are required to avoid a warning when compiling.</p>
 441
 442 <p>Here is the definition of the function <strong>afb_req_context</strong></p>
 443
 444 <pre><code>/*
 445  * Gets the pointer stored by the plugin for the session of 'req'.
 446  * If the stored pointer is NULL, indicating that no pointer was
 447  * already stored, afb_req_context creates a new context by calling
 448  * the function 'create_context' and stores it with the freeing function
 449  * 'free_context'.
 450  */
 451 static inline void *afb_req_context(struct afb_req req, void *(*create_context)(), void (*free_context)(void*))
 452 {
 453     void *result = afb_req_context_get(req);
 454     if (result == NULL) {
 455         result = create_context();
 456         afb_req_context_set(req, result, free_context);
 457     }
 458     return result;
 459 }
 460 </code></pre>
 461
 462 <p>This powerful function ensures that the context exists and is
 463 stored for the session.</p>
 464
 465 <p>The function <strong>get_new_board</strong> creates a new board and set its
 466 count of use to 1. The boards are counting their count of use
 467 to free there ressources when no more used.</p>
 468
 469 <p>The function <strong>release_board</strong></p>
 470
 471 <a name="Sending.the.reply.to.a.request"></a>
 472 <h3>Sending the reply to a request</h3>
 473
 474 <a name="Getting.argument.of.invocation"></a>
 475 <h2>Getting argument of invocation</h2>
 476
 477 <a name="How.to.build.a.plugin"></a>
 478 <h2>How to build a plugin</h2>
 479
 480 <p>Afb-daemon provides a The packaging of afb-daemon</p>
 481 </body>
 482 </html>