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 <h1 id="HOWTO.WRITE.a.PLUGIN.for.AFB-DAEMON">HOWTO WRITE a PLUGIN for AFB-DAEMON</h1>
   8
   9 <pre><code>version: 1
  10 Date:    25 May 2016
  11 Author:  José Bollo
  12 </code></pre>
  13
  14 <p><ul>
  15  <li><a href="#HOWTO.WRITE.a.PLUGIN.for.AFB-DAEMON">HOWTO WRITE a PLUGIN for AFB-DAEMON</a>
  16  <ul>
  17   <li><a href="#Summary">Summary</a>
  18   <ul>
  19    <li><a href="#Nature.of.a.plugin">Nature of a plugin</a></li>
  20    <li><a href="#Kinds.of.plugins">Kinds of plugins</a>
  21    <ul>
  22     <li><a href="#Application.plugins">Application plugins</a></li>
  23     <li><a href="#Service.plugins">Service plugins</a></li>
  24    </ul>
  25    </li>
  26    <li><a href="#Live.cycle.of.a.plugin.within.afb-daemon">Live cycle of a plugin within afb-daemon</a></li>
  27    <li><a href="#Content.of.a.plugin">Content of a plugin</a>
  28    <ul>
  29     <li><a href="#The.name.of.the.plugin">The name of the plugin</a></li>
  30     <li><a href="#Names.of.verbs">Names of verbs</a></li>
  31     <li><a href="#The.initialisation.function">The initialisation function</a></li>
  32     <li><a href="#Functions.implementing.verbs">Functions implementing verbs</a>
  33 </li>
  34    </ul>
  35    </li>
  36   </ul>
  37   </li>
  38   <li><a href="#The.Tic-Tac-Toe.example">The Tic-Tac-Toe example</a></li>
  39   <li><a href="#Choosing.names">Choosing names</a>
  40   <ul>
  41    <li><a href="#Names.for.API..plugin.">Names for API (plugin)</a></li>
  42    <li><a href="#Names.for.verbs">Names for verbs</a></li>
  43    <li><a href="#Names.for.arguments">Names for arguments</a></li>
  44    <li><a href="#Forging.names.widely.available">Forging names widely available</a></li>
  45   </ul>
  46   </li>
  47   <li><a href="#Options.to.set.when.compiling.plugins">Options to set when compiling plugins</a></li>
  48   <li><a href="#Header.files.to.include">Header files to include</a></li>
  49   <li><a href="#Writing.a.synchronous.verb.implementation">Writing a synchronous verb implementation</a>
  50   <ul>
  51    <li><a href="#The.incoming.request">The incoming request</a></li>
  52    <li><a href="#Associating.a.context.to.the.session">Associating a context to the session</a></li>
  53    <li><a href="#Sending.the.reply.to.a.request">Sending the reply to a request</a></li>
  54   </ul>
  55   </li>
  56   <li><a href="#Getting.argument.of.invocation">Getting argument of invocation</a>
  57   <ul>
  58    <li><a href="#Basic.functions.for.querying.arguments">Basic functions for querying arguments</a></li>
  59    <li><a href="#Arguments.for.received.files">Arguments for received files</a></li>
  60    <li><a href="#Arguments.as.a.JSON.object">Arguments as a JSON object</a></li>
  61   </ul>
  62   </li>
  63   <li><a href="#Sending.messages.to.the.log.system">Sending messages to the log system</a></li>
  64   <li><a href="#How.to.build.a.plugin">How to build a plugin</a></li>
  65  </ul>
  66  </li>
  67 </ul></p>
  68
  69 <h2 id="Summary">Summary</h2>
  70
  71 <p>The binder afb-daemon serves files through
  72 the HTTP protocol and offers access to API&rsquo;s through
  73 HTTP or WebSocket protocol.</p>
  74
  75 <p>The plugins are used to add API&rsquo;s to afb-daemon.
  76 This part describes how to write a plugin for afb-daemon.
  77 Excepting this summary, this part is intended to be read
  78 by developpers.</p>
  79
  80 <p>Before going into details, through a tiny example,
  81 a short overview plugins basis is needed.</p>
  82
  83 <h3 id="Nature.of.a.plugin">Nature of a plugin</h3>
  84
  85 <p>A plugin is a separate piece of code made of a shared library.
  86 The plugin is loaded and activated by afb-daemon when afb-daemon
  87 starts.</p>
  88
  89 <p>Technically, a plugin is not linked to any library of afb-daemon.</p>
  90
  91 <h3 id="Kinds.of.plugins">Kinds of plugins</h3>
  92
  93 <p>There is two kinds of plugins: application plugins and service
  94 plugins.</p>
  95
  96 <h4 id="Application.plugins">Application plugins</h4>
  97
  98 <p>Application plugins are intended to be instanciated for each
  99 application: when an application using that plugin is started,
 100 its binder starts a new instance of the plugin.</p>
 101
 102 <p>It means that the application plugins mainly have only one
 103 context to manage for one client.</p>
 104
 105 <h4 id="Service.plugins">Service plugins</h4>
 106
 107 <p>Service plugins are intended to be instanciated only one time
 108 only and connected to many clients.</p>
 109
 110 <p>So either it does not manage context at all or otherwise,
 111 if it manages context, it should be able to manage one context
 112 per client.</p>
 113
 114 <p>In details, it may be useful to have service plugins at a user
 115 level.</p>
 116
 117 <h3 id="Live.cycle.of.a.plugin.within.afb-daemon">Live cycle of a plugin within afb-daemon</h3>
 118
 119 <p>The plugins are loaded and activated when afb-daemon starts.</p>
 120
 121 <p>At start, the plugin initialise itself.
 122 If it fails to initialise then afb-daemon stops.</p>
 123
 124 <p>Conversely, if it success to initialize, it must declare
 125 a name, that must be unique, and a list of API&rsquo;s verbs.</p>
 126
 127 <p>When initialized, the functions implementing the API&rsquo;s verbs
 128 of the plugin are activated on call.</p>
 129
 130 <p>At the end, nothing special is done by afb-daemon.
 131 Consequently, developpers of plugins should use &lsquo;atexit&rsquo;
 132 or &lsquo;on_exit&rsquo; during initialisation if they need to
 133 perform specific actions when stopping.</p>
 134
 135 <h3 id="Content.of.a.plugin">Content of a plugin</h3>
 136
 137 <p>For afb-daemon, a plugin contains 2 different
 138 things: names and functions.</p>
 139
 140 <p>There is two kind of names:
 141  - the name of the plugin,
 142  - the names of the verbs.</p>
 143
 144 <p>There is two kind of functions:
 145  - the initialisation function
 146  - functions implementing verbs</p>
 147
 148 <p>Afb-daemon translates the name of the method that is
 149 invoked to a pair of API and verb names. For example,
 150 the method named <strong>foo/bar</strong> translated to the API
 151 name <strong>foo</strong> and the verb name <strong>bar</strong>.
 152 To serve it, afb-daemon search the plugin that record
 153 the name <strong>foo</strong> and if it also recorded the verb <strong>bar</strong>,
 154 it calls the implementation function declared for this verb.</p>
 155
 156 <p>Afb-daemon make no distinction between lower case
 157 and upper case when searching for a method.
 158 Thus, The names <strong>TicTacToe/Board</strong> and <strong>tictactoe/borad</strong>
 159 are equals.</p>
 160
 161 <h4 id="The.name.of.the.plugin">The name of the plugin</h4>
 162
 163 <p>The name of the plugin is also known as the name
 164 of the API that defines the plugin.</p>
 165
 166 <p>This name is also known as the prefix.</p>
 167
 168 <p>The name of a plugin MUST be unique within afb-daemon.</p>
 169
 170 <p>For example, when a client of afb-daemon
 171 calls a method named <strong>foo/bar</strong>. Afb-daemon
 172 extracts the prefix <strong>foo</strong> and the suffix <strong>bar</strong>.
 173 <strong>foo</strong> is the API name and must match a plugin name,
 174 the plugin that implements the verb <strong>bar</strong>.</p>
 175
 176 <h4 id="Names.of.verbs">Names of verbs</h4>
 177
 178 <p>Each plugin exposes a set of verbs that can be called
 179 by client of afb-daemon.</p>
 180
 181 <p>The name of a verb MUST be unique within a plugin.</p>
 182
 183 <p>Plugins link verbs to functions that are called
 184 when clients emit requests for that verb.</p>
 185
 186 <p>For example, when a client of afb-daemon
 187 calls a method named <strong>foo/bar</strong>.</p>
 188
 189 <h4 id="The.initialisation.function">The initialisation function</h4>
 190
 191 <p>The initialisation function serves several purposes.</p>
 192
 193 <ol>
 194 <li><p>It allows afb-daemon to check the version
 195 of the plugin using the name of the initialisation
 196 functions that it found. Currently, the initialisation
 197 function is named <strong>pluginAfbV1Register</strong>. It identifies
 198 the first version of plugins.</p></li>
 199 <li><p>It allows the plugin to initialise itself.</p></li>
 200 <li><p>It serves to the plugin to declare names, descriptions,
 201 requirements and implmentations of the verbs that it exposes.</p></li>
 202 </ol>
 203
 204
 205 <h4 id="Functions.implementing.verbs">Functions implementing verbs</h4>
 206
 207 <p>When a method is called, afb-daemon constructs a request
 208 object and pass it to the implementation function for verb
 209 within the plugin of the API.</p>
 210
 211 <p>An implementation function receives a request object that
 212 is used to get arguments of the request, to send
 213 answer, to store session data.</p>
 214
 215 <p>A plugin MUST send an answer to the request.</p>
 216
 217 <p>But it is not mandatory to send the answer
 218 before to return from the implementing function.
 219 This behaviour is important for implementing
 220 asynchronous actions.</p>
 221
 222 <p>Implementation functions that always reply to the request
 223 before returning are named <em>synchronous implementations</em>.
 224 Those that don&rsquo;t always reply to the request before
 225 returning are named <em>asynchronous implementations</em>.</p>
 226
 227 <p>Asynchronous implementations typically initiate an
 228 asynchronous action and record to send the reply
 229 on completion of this action.</p>
 230
 231 <h2 id="The.Tic-Tac-Toe.example">The Tic-Tac-Toe example</h2>
 232
 233 <p>This part explains how to write an afb-plugin.
 234 For the sake of being practical we will use many
 235 examples from the tic-tac-toe example.
 236 This plugin example is in <em>plugins/samples/tic-tac-toe.c</em>.</p>
 237
 238 <p>This plugin is named <strong><em>tictactoe</em></strong>.</p>
 239
 240 <h2 id="Choosing.names">Choosing names</h2>
 241
 242 <p>The designer of a plugin must defines names for its plugin
 243 (or its API) and for the verbs of its API. He also
 244 must defines names for arguments given by name.</p>
 245
 246 <p>While forging names, the designer should take into account
 247 the rules for making valid names and some rules that make
 248 the names easy to use across plaforms.</p>
 249
 250 <p>The names and strings used ALL are UTF-8 encoded.</p>
 251
 252 <h3 id="Names.for.API..plugin.">Names for API (plugin)</h3>
 253
 254 <p>The names of the API are checked.
 255 All characters are authorised except:</p>
 256
 257 <ul>
 258 <li>the control characters (\u0000 .. \u001f)</li>
 259 <li>the characters of the set { &lsquo; &rsquo;, &lsquo;&ldquo;&rsquo;, &lsquo;#&rsquo;, &lsquo;%&rsquo;, &lsquo;&amp;&rsquo;,
 260 &lsquo;&rsquo;&lsquo;, &rsquo;/&lsquo;, &rsquo;?&lsquo;, &rsquo;`&lsquo;, &rsquo;\x7f' }</li>
 261 </ul>
 262
 263
 264 <p>In other words the set of forbidden characters is
 265 { \u0000..\u0020, \u0022, \u0023, \u0025..\u0027,
 266   \u002f, \u003f, \u0060, \u007f }.</p>
 267
 268 <p>Afb-daemon make no distinction between lower case
 269 and upper case when searching for an API by its name.</p>
 270
 271 <h3 id="Names.for.verbs">Names for verbs</h3>
 272
 273 <p>The names of the verbs are not checked.</p>
 274
 275 <p>However, the validity rules for verb&rsquo;s names are the
 276 same as for API&rsquo;s names except that the dot (.) character
 277 is forbidden.</p>
 278
 279 <p>Afb-daemon make no distinction between lower case
 280 and upper case when searching for an API by its name.</p>
 281
 282 <h3 id="Names.for.arguments">Names for arguments</h3>
 283
 284 <p>The names for arguments are not restricted and can be
 285 anything.</p>
 286
 287 <p>The arguments are searched with the case sensitive
 288 string comparison. Thus the names &ldquo;index&rdquo; and &ldquo;Index&rdquo;
 289 are not the same.</p>
 290
 291 <h3 id="Forging.names.widely.available">Forging names widely available</h3>
 292
 293 <p>The key names of javascript object can be almost
 294 anything using the arrayed notation:</p>
 295
 296 <pre><code>object[key] = value
 297 </code></pre>
 298
 299 <p>That is not the case with the dot notation:</p>
 300
 301 <pre><code>object.key = value
 302 </code></pre>
 303
 304 <p>Using the dot notation, the key must be a valid javascript
 305 identifier.</p>
 306
 307 <p>For this reason, the chosen names should better be
 308 valid javascript identifier.</p>
 309
 310 <p>It is also a good practice, even for arguments, to not
 311 rely on the case sensitivity and to avoid the use of
 312 names different only by the case.</p>
 313
 314 <h2 id="Options.to.set.when.compiling.plugins">Options to set when compiling plugins</h2>
 315
 316 <p>Afb-daemon provides a configuration file for <em>pkg-config</em>.
 317 Typing the command</p>
 318
 319 <pre><code>pkg-config --cflags afb-daemon
 320 </code></pre>
 321
 322 <p>will print the flags to use for compiling, like this:</p>
 323
 324 <pre><code>$ pkg-config --cflags afb-daemon
 325 -I/opt/local/include -I/usr/include/json-c
 326 </code></pre>
 327
 328 <p>For linking, you should use</p>
 329
 330 <pre><code>$ pkg-config --libs afb-daemon
 331 -ljson-c
 332 </code></pre>
 333
 334 <p>As you see, afb-daemon automatically includes dependency to json-c.
 335 This is done through the <strong>Requires</strong> keyword of pkg-config.</p>
 336
 337 <p>If this behaviour is a problem, let us know.</p>
 338
 339 <h2 id="Header.files.to.include">Header files to include</h2>
 340
 341 <p>The plugin <em>tictactoe</em> has the following lines for its includes:</p>
 342
 343 <pre><code>#define _GNU_SOURCE
 344 #include &lt;stdio.h&gt;
 345 #include &lt;string.h&gt;
 346 #include &lt;json-c/json.h&gt;
 347 #include &lt;afb/afb-plugin.h&gt;
 348 </code></pre>
 349
 350 <p>The header <em>afb/afb-plugin.h</em> includes all the features that a plugin
 351 needs except two foreign header that must be included by the plugin
 352 if it needs it:</p>
 353
 354 <ul>
 355 <li><em>json-c/json.h</em>: this header must be include to handle json objects;</li>
 356 <li><em>systemd/sd-event.h</em>: this must be include to access the main loop;</li>
 357 <li><em>systemd/sd-bus.h</em>: this may be include to use dbus connections.</li>
 358 </ul>
 359
 360
 361 <p>The <em>tictactoe</em> plugin does not use systemd features so it is not included.</p>
 362
 363 <p>When including <em>afb/afb-plugin.h</em>, the macro <strong>_GNU_SOURCE</strong> must be
 364 defined.</p>
 365
 366 <h2 id="Writing.a.synchronous.verb.implementation">Writing a synchronous verb implementation</h2>
 367
 368 <p>The verb <strong>tictactoe/board</strong> is a synchronous implementation.
 369 Here is its listing:</p>
 370
 371 <pre><code>/*
 372  * get the board
 373  */
 374 static void board(struct afb_req req)
 375 {
 376         struct board *board;
 377         struct json_object *description;
 378
 379         /* retrieves the context for the session */
 380         board = board_of_req(req);
 381         INFO(afbitf, "method 'board' called for boardid %d", board-&gt;id);
 382
 383         /* describe the board */
 384         description = describe(board);
 385
 386         /* send the board's description */
 387         afb_req_success(req, description, NULL);
 388 }
 389 </code></pre>
 390
 391 <p>This examples show many aspects of writing a synchronous
 392 verb implementation. Let summarize it:</p>
 393
 394 <ol>
 395 <li><p>The function <strong>board_of_req</strong> retrieves the context stored
 396 for the plugin: the board.</p></li>
 397 <li><p>The macro <strong>INFO</strong> sends a message of kind <em>INFO</em>
 398 to the logging system. The global variable named <strong>afbitf</strong>
 399 used represents the interface to afb-daemon.</p></li>
 400 <li><p>The function <strong>describe</strong> creates a json_object representing
 401 the board.</p></li>
 402 <li><p>The function <strong>afb_req_success</strong> sends the reply, attaching to
 403 it the object <em>description</em>.</p></li>
 404 </ol>
 405
 406
 407 <h3 id="The.incoming.request">The incoming request</h3>
 408
 409 <p>For any implementation, the request is received by a structure of type
 410 <strong>struct afb_req</strong>.</p>
 411
 412 <blockquote><p>Note that this is a PLAIN structure, not a pointer to a structure.</p></blockquote>
 413
 414 <p>The definition of <strong>struct afb_req</strong> is:</p>
 415
 416 <pre><code>/*
 417  * Describes the request by plugins from afb-daemon
 418  */
 419 struct afb_req {
 420         const struct afb_req_itf *itf;  /* the interfacing functions */
 421         void *closure;          /* the closure for functions */
 422 };
 423 </code></pre>
 424
 425 <p>It contains two pointers: one, <em>itf</em>, points to the functions needed
 426 to handle the internal request represented by the second pointer, <em>closure</em>.</p>
 427
 428 <blockquote><p>The structure must never be used directly.
 429 Insted, use the intended functions provided
 430 by afb-daemon and described here.</p></blockquote>
 431
 432 <p><em>req</em> is used to get arguments of the request, to send
 433 answer, to store session data.</p>
 434
 435 <p>This object and its interface is defined and documented
 436 in the file names <em>afb/afb-req-itf.h</em></p>
 437
 438 <p>The above example uses 2 times the request object <em>req</em>.</p>
 439
 440 <p>The first time, it is used for retrieving the board attached to
 441 the session of the request.</p>
 442
 443 <p>The second time, it is used to send the reply: an object that
 444 describes the current board.</p>
 445
 446 <h3 id="Associating.a.context.to.the.session">Associating a context to the session</h3>
 447
 448 <p>When the plugin <em>tic-tac-toe</em> receives a request, it musts regain
 449 the board that describes the game associated to the session.</p>
 450
 451 <p>For a plugin, having data associated to a session is a common case.
 452 This data is called the context of the plugin for the session.
 453 For the plugin <em>tic-tac-toe</em>, the context is the board.</p>
 454
 455 <p>The requests <em>afb_req</em> offer four functions for
 456 storing and retrieving the context associated to the session.</p>
 457
 458 <p>These functions are:</p>
 459
 460 <ul>
 461 <li><p><strong>afb_req_context_get</strong>:
 462 retrieves the context data stored for the plugin.</p></li>
 463 <li><p><strong>afb_req_context_set</strong>:
 464 store the context data of the plugin.</p></li>
 465 <li><p><strong>afb_req_context</strong>:
 466 retrieves the context data of the plugin,
 467 if needed, creates the context and store it.</p></li>
 468 <li><p><strong>afb_req_context_clear</strong>:
 469 reset the stored data.</p></li>
 470 </ul>
 471
 472
 473 <p>The plugin <em>tictactoe</em> use a convenient function to retrieve
 474 its context: the board. This function is <em>board_of_req</em>:</p>
 475
 476 <pre><code>/*
 477  * retrieves the board of the request
 478  */
 479 static inline struct board *board_of_req(struct afb_req req)
 480 {
 481         return afb_req_context(req, (void*)get_new_board, (void*)release_board);
 482 }
 483 </code></pre>
 484
 485 <p>The function <strong>afb_req_context</strong> ensure an existing context
 486 for the session of the request.
 487 Its two last arguments are functions. Here, the casts are required
 488 to avoid a warning when compiling.</p>
 489
 490 <p>Here is the definition of the function <strong>afb_req_context</strong></p>
 491
 492 <pre><code>/*
 493  * Gets the pointer stored by the plugin for the session of 'req'.
 494  * If the stored pointer is NULL, indicating that no pointer was
 495  * already stored, afb_req_context creates a new context by calling
 496  * the function 'create_context' and stores it with the freeing function
 497  * 'free_context'.
 498  */
 499 static inline void *afb_req_context(struct afb_req req, void *(*create_context)(), void (*free_context)(void*))
 500 {
 501         void *result = afb_req_context_get(req);
 502         if (result == NULL) {
 503                 result = create_context();
 504                 afb_req_context_set(req, result, free_context);
 505         }
 506         return result;
 507 }
 508 </code></pre>
 509
 510 <p>The second argument if the function that creates the context.
 511 For the plugin <em>tic-tac-toe</em> it is the function <strong>get_new_board</strong>.
 512 The function <strong>get_new_board</strong> creates a new board and set its
 513 count of use to 1. The boards are counting their count of use
 514 to free there ressources when no more used.</p>
 515
 516 <p>The third argument if the function that frees the context.
 517 For the plugin <em>tic-tac-toe</em> it is the function <strong>release_board</strong>.
 518 The function <strong>release_board</strong> decrease the the count of use of
 519 the board given as argument. If the use count decrease to zero,
 520 the board data are freed.</p>
 521
 522 <p>The definition of the other functions for dealing with contexts are:</p>
 523
 524 <pre><code>/*
 525  * Gets the pointer stored by the plugin for the session of 'req'.
 526  * When the plugin has not yet recorded a pointer, NULL is returned.
 527  */
 528 void *afb_req_context_get(struct afb_req req);
 529
 530 /*
 531  * Stores for the plugin the pointer 'context' to the session of 'req'.
 532  * The function 'free_context' will be called when the session is closed
 533  * or if plugin stores an other pointer.
 534  */
 535 void afb_req_context_set(struct afb_req req, void *context, void (*free_context)(void*));
 536
 537 /*
 538  * Frees the pointer stored by the plugin for the session of 'req'
 539  * and sets it to NULL.
 540  *
 541  * Shortcut for: afb_req_context_set(req, NULL, NULL)
 542  */
 543 static inline void afb_req_context_clear(struct afb_req req)
 544 {
 545         afb_req_context_set(req, NULL, NULL);
 546 }
 547 </code></pre>
 548
 549 <h3 id="Sending.the.reply.to.a.request">Sending the reply to a request</h3>
 550
 551 <p>Two kinds of replies can be made: successful replies and
 552 failure replies.</p>
 553
 554 <blockquote><p>Sending a reply to a request must be done at most one time.</p></blockquote>
 555
 556 <p>The two functions to send a reply of kind &ldquo;success&rdquo; are
 557 <strong>afb_req_success</strong> and <strong>afb_req_success_f</strong>.</p>
 558
 559 <pre><code>/*
 560  * Sends a reply of kind success to the request 'req'.
 561  * The status of the reply is automatically set to "success".
 562  * Its send the object 'obj' (can be NULL) with an
 563  * informationnal comment 'info (can also be NULL).
 564  */
 565 void afb_req_success(struct afb_req req, struct json_object *obj, const char *info);
 566
 567 /*
 568  * Same as 'afb_req_success' but the 'info' is a formatting
 569  * string followed by arguments.
 570  */
 571 void afb_req_success_f(struct afb_req req, struct json_object *obj, const char *info, ...);
 572 </code></pre>
 573
 574 <p>The two functions to send a reply of kind &ldquo;failure&rdquo; are
 575 <strong>afb_req_fail</strong> and <strong>afb_req_fail_f</strong>.</p>
 576
 577 <pre><code>/*
 578  * Sends a reply of kind failure to the request 'req'.
 579  * The status of the reply is set to 'status' and an
 580  * informationnal comment 'info' (can also be NULL) can be added.
 581  *
 582  * Note that calling afb_req_fail("success", info) is equivalent
 583  * to call afb_req_success(NULL, info). Thus even if possible it
 584  * is strongly recommanded to NEVER use "success" for status.
 585  */
 586 void afb_req_fail(struct afb_req req, const char *status, const char *info);
 587
 588 /*
 589  * Same as 'afb_req_fail' but the 'info' is a formatting
 590  * string followed by arguments.
 591  */
 592 void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...);
 593 </code></pre>
 594
 595 <h2 id="Getting.argument.of.invocation">Getting argument of invocation</h2>
 596
 597 <p>Many verbs expect arguments. Afb-daemon let plugins
 598 retrieve their arguments by name not by position.</p>
 599
 600 <p>Arguments are given by the requests either through HTTP
 601 or through WebSockets.</p>
 602
 603 <p>For example, the verb <strong>join</strong> of the plugin <strong>tic-tac-toe</strong>
 604 expects one argument: the <em>boardid</em> to join. Here is an extract:</p>
 605
 606 <pre><code>/*
 607  * Join a board
 608  */
 609 static void join(struct afb_req req)
 610 {
 611         struct board *board, *new_board;
 612         const char *id;
 613
 614         /* retrieves the context for the session */
 615         board = board_of_req(req);
 616         INFO(afbitf, "method 'join' called for boardid %d", board-&gt;id);
 617
 618         /* retrieves the argument */
 619         id = afb_req_value(req, "boardid");
 620         if (id == NULL)
 621                 goto bad_request;
 622         ...
 623 </code></pre>
 624
 625 <p>The function <strong>afb_req_value</strong> search in the request <em>req</em>
 626 for an argument whose name is given. When no argument of the
 627 given name was passed, <strong>afb_req_value</strong> returns NULL.</p>
 628
 629 <blockquote><p>The search is case sensitive. So the name <em>boardid</em> is not the
 630 same name than <em>BoardId</em>. But this must not be assumed so two
 631 expected names of argument should not differ only by case.</p></blockquote>
 632
 633 <h3 id="Basic.functions.for.querying.arguments">Basic functions for querying arguments</h3>
 634
 635 <p>The function <strong>afb_req_value</strong> is defined as below:</p>
 636
 637 <pre><code>/*
 638  * Gets from the request 'req' the string value of the argument of 'name'.
 639  * Returns NULL if when there is no argument of 'name'.
 640  * Returns the value of the argument of 'name' otherwise.
 641  *
 642  * Shortcut for: afb_req_get(req, name).value
 643  */
 644 static inline const char *afb_req_value(struct afb_req req, const char *name)
 645 {
 646         return afb_req_get(req, name).value;
 647 }
 648 </code></pre>
 649
 650 <p>It is defined as a shortcut to call the function <strong>afb_req_get</strong>.
 651 That function is defined as below:</p>
 652
 653 <pre><code>/*
 654  * Gets from the request 'req' the argument of 'name'.
 655  * Returns a PLAIN structure of type 'struct afb_arg'.
 656  * When the argument of 'name' is not found, all fields of result are set to NULL.
 657  * When the argument of 'name' is found, the fields are filled,
 658  * in particular, the field 'result.name' is set to 'name'.
 659  *
 660  * There is a special name value: the empty string.
 661  * The argument of name "" is defined only if the request was made using
 662  * an HTTP POST of Content-Type "application/json". In that case, the
 663  * argument of name "" receives the value of the body of the HTTP request.
 664  */
 665 struct afb_arg afb_req_get(struct afb_req req, const char *name);
 666 </code></pre>
 667
 668 <p>That function takes 2 parameters: the request and the name
 669 of the argument to retrieve. It returns a PLAIN structure of
 670 type <strong>struct afb_arg</strong>.</p>
 671
 672 <p>There is a special name that is defined when the request is
 673 of type HTTP/POST with a Content-Type being application/json.
 674 This name is <strong>&ldquo;&rdquo;</strong> (the empty string). In that case, the value
 675 of this argument of empty name is the string received as a body
 676 of the post and is supposed to be a JSON string.</p>
 677
 678 <p>The definition of <strong>struct afb_arg</strong> is:</p>
 679
 680 <pre><code>/*
 681  * Describes an argument (or parameter) of a request
 682  */
 683 struct afb_arg {
 684         const char *name;   /* name of the argument or NULL if invalid */
 685         const char *value;  /* string representation of the value of the argument */
 686                                 /* original filename of the argument if path != NULL */
 687         const char *path;   /* if not NULL, path of the received file for the argument */
 688                                 /* when the request is finalized this file is removed */
 689 };
 690 </code></pre>
 691
 692 <p>The structure returns the data arguments that are known for the
 693 request. This data include a field named <strong>path</strong>. This <strong>path</strong>
 694 can be accessed using the function <strong>afb_req_path</strong> defined as
 695 below:</p>
 696
 697 <pre><code>/*
 698  * Gets from the request 'req' the path for file attached to the argument of 'name'.
 699  * Returns NULL if when there is no argument of 'name' or when there is no file.
 700  * Returns the path of the argument of 'name' otherwise.
 701  *
 702  * Shortcut for: afb_req_get(req, name).path
 703  */
 704 static inline const char *afb_req_path(struct afb_req req, const char *name)
 705 {
 706         return afb_req_get(req, name).path;
 707 }
 708 </code></pre>
 709
 710 <p>The path is only defined for HTTP/POST requests that send file.</p>
 711
 712 <h3 id="Arguments.for.received.files">Arguments for received files</h3>
 713
 714 <p>As it is explained just above, clients can send files using
 715 HTTP/POST requests.</p>
 716
 717 <p>Received files are attached to a arguments. For example, the
 718 following HTTP fragment (from test/sample-post.html)
 719 will send an HTTP/POST request to the method
 720 <strong>post/upload-image</strong> with 2 arguments named <em>file</em> and
 721 <em>hidden</em>.</p>
 722
 723 <pre><code>&lt;h2&gt;Sample Post File&lt;/h2&gt;
 724 &lt;form enctype="multipart/form-data"&gt;
 725     &lt;input type="file" name="file" /&gt;
 726     &lt;input type="hidden" name="hidden" value="bollobollo" /&gt;
 727     &lt;br&gt;
 728     &lt;button formmethod="POST" formaction="api/post/upload-image"&gt;Post File&lt;/button&gt;
 729 &lt;/form&gt;
 730 </code></pre>
 731
 732 <p>In that case, the argument named <strong>file</strong> has its value and its
 733 path defined and not NULL.</p>
 734
 735 <p>The value is the name of the file as it was
 736 set by the HTTP client and is generally the filename on the
 737 client side.</p>
 738
 739 <p>The path is the path of the file saved on the temporary local storage
 740 area of the application. This is a randomly generated and unic filename
 741 not linked in any way with the original filename on the client.</p>
 742
 743 <p>The plugin can use the file at the given path the way that it wants:
 744 read, write, remove, copy, rename&hellip;
 745 But when the reply is sent and the query is terminated, the file at
 746 this path is destroyed if it still exist.</p>
 747
 748 <h3 id="Arguments.as.a.JSON.object">Arguments as a JSON object</h3>
 749
 750 <p>Plugins can get all the arguments as one single object.
 751 This feature is provided by the function <strong>afb_req_json</strong>
 752 that is defined as below:</p>
 753
 754 <pre><code>/*
 755  * Gets from the request 'req' the json object hashing the arguments.
 756  * The returned object must not be released using 'json_object_put'.
 757  */
 758 struct json_object *afb_req_json(struct afb_req req);
 759 </code></pre>
 760
 761 <p>It returns a json object. This object depends on how the request was
 762 made:</p>
 763
 764 <ul>
 765 <li><p>For HTTP requests, this is an object whose keys are the names of the
 766 arguments and whose values are either a string for common arguments or
 767 an object like { &ldquo;file&rdquo;: &ldquo;&hellip;&rdquo;, &ldquo;path&rdquo;: &ldquo;&hellip;&rdquo; }</p></li>
 768 <li><p>For WebSockets requests, the returned object is the object
 769 given by the client transparently transported.</p></li>
 770 </ul>
 771
 772
 773 <blockquote><p>In fact, for Websockets requests, the function <strong>afb_req_value</strong>
 774 can be seen as a shortcut to
 775 <em>json_object_get_string(json_object_object_get(afb_req_json(req), name))</em></p></blockquote>
 776
 777 <h2 id="Sending.messages.to.the.log.system">Sending messages to the log system</h2>
 778
 779 <h2 id="How.to.build.a.plugin">How to build a plugin</h2>
 780
 781 <p>Afb-daemon provides a <em>pkg-config</em> configuration file.</p>
 782 </body>
 783 </html>