include/babeltrace/plugin/plugin-system.h

   1 #ifndef BABELTRACE_PLUGIN_SYSTEM_H
   2 #define BABELTRACE_PLUGIN_SYSTEM_H
   3
   4 /*
   5  * BabelTrace - Babeltrace Plug-in System Interface
   6  *
   7  * This interface is provided for plug-ins to use the Babeltrace
   8  * plug-in system facilities.
   9  *
  10  * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
  11  *
  12  * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  13  *
  14  * Permission is hereby granted, free of charge, to any person obtaining a copy
  15  * of this software and associated documentation files (the "Software"), to deal
  16  * in the Software without restriction, including without limitation the rights
  17  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  18  * copies of the Software, and to permit persons to whom the Software is
  19  * furnished to do so, subject to the following conditions:
  20  *
  21  * The above copyright notice and this permission notice shall be included in
  22  * all copies or substantial portions of the Software.
  23  *
  24  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  25  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  26  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  27  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  28  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  29  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  30  * SOFTWARE.
  31  */
  32
  33 #include <babeltrace/plugin/notification/notification.h>
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 struct bt_notification;
  40 struct bt_notification_iterator;
  41 struct bt_component;
  42 struct bt_component_factory;
  43 struct bt_value;
  44
  45 typedef enum bt_component_status (*bt_plugin_init_func)(
  46                 struct bt_component_factory *factory);
  47 typedef void (*bt_plugin_exit_func)(void);
  48
  49 /**
  50  * Component private data deallocation function type.
  51  *
  52  * @param component     Component instance
  53  */
  54 typedef void (*bt_component_destroy_cb)(struct bt_component *component);
  55
  56 /**
  57  * Component initialization function type.
  58  *
  59  * A component's private data and required callbacks must be set by this
  60  * function.
  61  *
  62  * @param component     Component instance
  63  * @param params        A dictionary of component parameters
  64  * @returns             One of #bt_component_status values
  65  */
  66 typedef enum bt_component_status (*bt_component_init_cb)(
  67                 struct bt_component *component, struct bt_value *params);
  68
  69 /**
  70  * Get a component's private data.
  71  *
  72  * @param component     Component of which to get the private data
  73  * @returns             Component's private data
  74  */
  75 extern void *bt_component_get_private_data(struct bt_component *component);
  76
  77 /**
  78  * Set a component's private data.
  79  *
  80  * @param component     Component of which to set the private data
  81  * @param data          Component private data
  82  * @returns             One of #bt_component_status values
  83  */
  84 extern enum bt_component_status bt_component_set_private_data(
  85                 struct bt_component *component, void *data);
  86
  87 /**
  88  * Set a component's private data cleanup function.
  89  *
  90  * @param component     Component of which to set the private data destruction
  91  *                      function
  92  * @param data          Component private data clean-up function
  93  * @returns             One of #bt_component_status values
  94  */
  95 extern enum bt_component_status bt_component_set_destroy_cb(
  96                 struct bt_component *component,
  97                 bt_component_destroy_cb destroy);
  98
  99 /** bt_component_souce */
 100 /**
 101  * Iterator initialization function type.
 102  *
 103  * A notification iterator's private data, deinitialization, next, and get
 104  * callbacks must be set by this function.
 105  *
 106  * @param source        Source component instance
 107  * @param iterator      Notification iterator instance
 108  */
 109 typedef enum bt_component_status (*bt_component_source_init_iterator_cb)(
 110                 struct bt_component *, struct bt_notification_iterator *);
 111
 112 /**
 113  * Set a source component's iterator initialization function.
 114  *
 115  * @param source        Source component instance
 116  * @param init_iterator Notification iterator initialization callback
 117  */
 118 extern enum bt_component_status
 119 bt_component_source_set_iterator_init_cb(struct bt_component *source,
 120                 bt_component_source_init_iterator_cb init_iterator);
 121
 122 /** bt_component_sink */
 123 /**
 124  * Notification handling function type.
 125  *
 126  * A reference must be taken on the notification if the component has to
 127  * keep ownership of the notification beyond the invocation of the callback.
 128  *
 129  * @param sink          Sink component instance
 130  * @param notification  Notification to handle
 131  * @returns             One of #bt_component_status values
 132  */
 133 typedef enum bt_component_status (*bt_component_sink_handle_notification_cb)(
 134                 struct bt_component *, struct bt_notification *);
 135
 136 /**
 137  * Set a sink component's notification handling callback.
 138  *
 139  * @param sink                  Sink component instance
 140  * @param handle_notification   Notification handling callback
 141  * @returns                     One of #bt_component_status values
 142  */
 143 extern enum bt_component_status
 144 bt_component_sink_set_handle_notification_cb(struct bt_component *sink,
 145                 bt_component_sink_handle_notification_cb handle_notification);
 146
 147 /**
 148  * Register a sink to a given notification type.
 149  *
 150  * A sink is always registered to notifications of type
 151  * BT_NOTIFICATION_TYPE_EVENT. However, it may opt to receive any (or all)
 152  * other notification type(s).
 153  *
 154  * @param sink          Sink component instance.
 155  * @param type          One of #bt_notification_type
 156  * @returns             One of #bt_component_status
 157  */
 158 extern enum bt_component_status
 159 bt_component_sink_register_notification_type(struct bt_component *sink,
 160                 enum bt_notification_type type);
 161
 162 /** bt_component_notification_iterator */
 163 /**
 164  * Function returning an iterator's current notification.
 165  *
 166  * @param iterator      Notification iterator instance
 167  * @returns             A notification instance
 168  */
 169 typedef struct bt_notification *(*bt_notification_iterator_get_cb)(
 170                 struct bt_notification_iterator *iterator);
 171
 172 /**
 173  * Function advancing an iterator's position of one element.
 174  *
 175  * @param iterator      Notification iterator instance
 176  * @returns             One of #bt_notification_iterator_status values
 177  */
 178 typedef enum bt_notification_iterator_status (*bt_notification_iterator_next_cb)(
 179                 struct bt_notification_iterator *iterator);
 180
 181 /**
 182  * Function cleaning-up an iterator's private data on destruction.
 183  *
 184  * @param iterator      Notification iterator instance
 185  */
 186 typedef void (*bt_notification_iterator_destroy_cb)(
 187                 struct bt_notification_iterator *iterator);
 188
 189 /**
 190  * Set an iterator's "get" callback which return the current notification.
 191  *
 192  * @param iterator      Notification iterator instance
 193  * @param get           Notification return callback
 194  * @returns             One of #bt_notification_iterator_status values
 195  */
 196 extern enum bt_notification_iterator_status
 197 bt_notification_iterator_set_get_cb(struct bt_notification_iterator *iterator,
 198                 bt_notification_iterator_get_cb get);
 199
 200 /**
 201  * Set an iterator's "next" callback which advances the iterator's position.
 202  *
 203  * @param iterator      Notification iterator instance
 204  * @param next          Iterator "next" callback
 205  * @returns             One of #bt_notification_iterator_status values
 206  */
 207 extern enum bt_notification_iterator_status
 208 bt_notification_iterator_set_next_cb(struct bt_notification_iterator *iterator,
 209                 bt_notification_iterator_next_cb next);
 210
 211 /**
 212  * Set an iterator's "destroy" callback.
 213  *
 214  * @param iterator      Notification iterator instance
 215  * @param next          Iterator destruction callback
 216  * @returns             One of #bt_notification_iterator_status values
 217  */
 218 extern enum bt_notification_iterator_status
 219 bt_notification_iterator_set_destroy_cb(
 220                 struct bt_notification_iterator *iterator,
 221                 bt_notification_iterator_destroy_cb destroy);
 222
 223 /**
 224  * Set an iterator's private data.
 225  *
 226  * @param iterator      Notification iterator instance
 227  * @param data          Iterator private data
 228  * @returns             One of #bt_notification_iterator_status values
 229  */
 230 extern enum bt_notification_iterator_status
 231 bt_notification_iterator_set_private_data(
 232                 struct bt_notification_iterator *iterator, void *data);
 233
 234 /**
 235  * Get an iterator's private data.
 236  *
 237  * @param iterator      Notification iterator instance
 238  * @returns             Iterator instance private data
 239  */
 240 extern void *bt_notification_iterator_get_private_data(
 241                 struct bt_notification_iterator *iterator);
 242
 243 #ifdef __cplusplus
 244 }
 245 #endif
 246
 247 #endif /* BABELTRACE_PLUGIN_SYSTEM_H */