Debuginfo allows access to current logging output through telnet.
[olsrd.git] / README-callbacks
1
2    Using the callback API in OLSR
3 =========================================
4 by Aaron Kaplan (aaron@lo-res.org)
5
6 Since early 2011, OLSR has an internal callback API.  The idea behind it is,
7 that plugins and other parts of the code can inform each other about changes to
8 internal database structures.  For this purpose, the callback API offers
9 listeners/consumers datastructres which can trigger callbacks in the case of
10 changes to internal datastructures.
11
12 Such an event can either be:
13   * addition (for example of objects to the routing DB)
14   * deletion 
15   * change
16
17 The callback API knows "providers" and "consumers" and objects.  A provider is
18 a datastructure which can call callback functions for events for objects.  A
19 consumer is a datastructure which specifies who will consume the callback for
20 an event of an object.
21
22 Objects (such as routing DB entries)  are identified  by a unique name (that
23 is, a unique key in the form of a char*).
24
25
26 Example usage
27 ==============
28
29 In src/nhdp.{c,h} we want to trigger "add" events when a link changes.  First
30 of all in nhdp.c we define the key (unique name) for the object:
31
32    const char *CB_NHDP_LINK = "nhdp link";
33
34
35 Next, let's take a look at the init function:
36
37 nhdp_link_init(void) {
38   /* (...) */
39
40   /* initialize callback provider */
41   if (olsr_callback_prv_create(&nhdp_link_callback, CB_NHDP_LINK)) {
42         /* callback providers for internal databases are mandatory */
43         OLSR_ERROR(LOG_NHDP, "Callback provider for NHDP link database is
44 mandatory\n"); 
45     olsr_exit(1); 
46   } 
47 }
48
49 Here, we initialize the callback provider. Please note, that the CB_NHDP_LINK
50 key is passed as second parameter.
51
52
53
54 This code fragment shows how to destroy a callback provider:
55
56 void nhdp_link_cleanup(void) {
57   olsr_callback_prv_destroy(&nhdp_link_callback);
58   /* (...) */
59 }
60
61
62
63 And finally, this code shows how consumers get informed of the deletion of an
64 object (an nhdp link in this case, a similar case would be for an addition of
65 an object):
66
67 /**
68  * Delete a NHDP link
69  * @param link nhdp link pointer
70  */
71 void
72 nhdp_delete_link(struct nhdp_link *link) {
73
74
75   /* (...) */
76
77   /* inform everyone that object will be removed */
78   olsr_callback_remove_object(&nhdp_link_callback, link);
79
80   /* (...) */
81 }
82
83
84
85
86