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/objects.h>
  34 #include <babeltrace/objects.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 struct bt_notification;
  41 struct bt_notification_iterator;
  42 struct bt_component;
  43
  44 /**
  45  * Component private data deallocation function type.
  46  *
  47  * @param component     Component instance
  48  */
  49 typedef void (*bt_component_destroy_cb)(struct bt_component *component);
  50
  51 /**
  52  * Source component initialization function type.
  53  *
  54  * A source component's iterator initialization callback, private data and
  55  * deinitialization callback must be set by this function.
  56  *
  57  * @param component     Component instance
  58  * @returns             One of #bt_component_status values
  59  */
  60 typedef enum bt_component_status (*bt_component_source_init_cb)(
  61                 struct bt_component *component);
  62
  63 /**
  64  * Sink component initialization function type.
  65  *
  66  * A sink component's notification handling callback, private data and
  67  * deinitialization callback must be set by this function.
  68  *
  69  * @param component     Component instance
  70  * @returns             One of #bt_component_status values
  71  */
  72 typedef enum bt_component_status (*bt_component_sink_init_cb)(
  73                 struct bt_component *component);
  74
  75 /**
  76  * Iterator initialization function type.
  77  *
  78  * @param component     Component instance
  79  * @param iterator      Iterator instance
  80  */
  81 typedef enum bt_component_status (*bt_component_source_iterator_init_cb)(
  82                 struct bt_component *component,
  83                 struct bt_notification_iterator *iterator);
  84
  85 /**
  86  * Get a component's private data.
  87  *
  88  * @param component     Component of which to get the private data
  89  * @returns             Component's private data
  90  */
  91 extern void *bt_component_get_private_data(struct bt_component *component);
  92
  93 /**
  94  * Set a component's private data.
  95  *
  96  * @param component     Component of which to set the private data
  97  * @param data          Component private data
  98  * @returns             One of #bt_component_status values
  99  */
 100 extern enum bt_component_status bt_component_set_private_data(
 101                 struct bt_component *component, void *data);
 102
 103 /**
 104  * Set a component's private data cleanup function.
 105  *
 106  * @param component     Component of which to set the private data destruction
 107  *                      function
 108  * @param data          Component private data clean-up function
 109  * @returns             One of #bt_component_status values
 110  */
 111 extern enum bt_component_status bt_component_set_destroy_cb(
 112                 struct bt_component *component,
 113                 bt_component_destroy_cb destroy);
 114
 115 /** bt_component_souce */
 116 /**
 117  * Iterator initialization function type.
 118  *
 119  * A notification iterator's private data, deinitialization, next, and get
 120  * callbacks must be set by this function.
 121  *
 122  * @param component     Component instance
 123  * @param iterator      Notification iterator instance
 124  */
 125 typedef enum bt_component_status (*bt_component_source_init_iterator_cb)(
 126                 struct bt_component *component,
 127                 struct bt_notification_iterator *iterator);
 128
 129 /**
 130  * Set a source component's iterator initialization function.
 131  *
 132  * @param component     Component instance
 133  * @param init_iterator Notification iterator initialization callback
 134  */
 135 extern enum bt_component_status
 136 bt_component_source_set_iterator_init_cb(struct bt_component *component,
 137                 bt_component_source_init_iterator_cb init_iterator);
 138
 139 /** bt_component_sink */
 140 /**
 141  * Notification handling function type.
 142  *
 143  * @param component     Component instance
 144  * @param notificattion Notification to handle
 145  * @returns             One of #bt_component_status values
 146  */
 147 typedef enum bt_component_status (*bt_component_sink_handle_notification_cb)(
 148                 struct bt_component *, struct bt_notification *);
 149
 150 /**
 151  * Set a sink component's notification handling callback.
 152  *
 153  * @param component             Component instance
 154  * @param handle_notification   Notification handling callback
 155  * @returns                     One of #bt_component_status values
 156  */
 157 extern enum bt_component_status
 158 bt_component_sink_set_handle_notification_cb(struct bt_component *component,
 159                 bt_component_sink_handle_notification_cb handle_notification);
 160
 161 /** bt_component_notification_iterator */
 162 /**
 163  * Function returning an iterator's current notification.
 164  *
 165  * @param iterator      Notification iterator instance
 166  * @returns             A notification instance
 167  */
 168 typedef struct bt_notification *(*bt_notification_iterator_get_cb)(
 169                 struct bt_notification_iterator *iterator);
 170
 171 /**
 172  * Function advancing an iterator's position of one element.
 173  *
 174  * @param iterator      Notification iterator instance
 175  * @returns             One of #bt_notification_iterator_status values
 176  */
 177 typedef enum bt_notification_iterator_status (*bt_notification_iterator_next_cb)(
 178                 struct bt_notification_iterator *iterator);
 179
 180 /**
 181  * Function cleaning-up an iterator's private data on destruction.
 182  *
 183  * @param iterator      Notification iterator instance
 184  */
 185 typedef void (*bt_notification_iterator_destroy_cb)(
 186                 struct bt_notification_iterator *iterator);
 187
 188 /**
 189  * Set an iterator's "get" callback which return the current notification.
 190  *
 191  * @param iterator      Notification iterator instance
 192  * @param get           Notification return callback
 193  * @returns             One of #bt_notification_iterator_status values
 194  */
 195 extern enum bt_notification_iterator_status
 196 bt_notification_iterator_set_get_cb(struct bt_notification_iterator *iterator,
 197                 bt_notification_iterator_get_cb get);
 198
 199 /**
 200  * Set an iterator's "next" callback which advances the iterator's position.
 201  *
 202  * @param iterator      Notification iterator instance
 203  * @param next          Iterator "next" callback
 204  * @returns             One of #bt_notification_iterator_status values
 205  */
 206 extern enum bt_notification_iterator_status
 207 bt_notification_iterator_set_next_cb(struct bt_notification_iterator *iterator,
 208                 bt_notification_iterator_next_cb next);
 209
 210 /**
 211  * Set an iterator's "destroy" callback.
 212  *
 213  * @param iterator      Notification iterator instance
 214  * @param next          Iterator destruction callback
 215  * @returns             One of #bt_notification_iterator_status values
 216  */
 217 extern enum bt_notification_iterator_status
 218 bt_notification_iterator_set_destroy_cb(
 219                 struct bt_notification_iterator *iterator,
 220                 bt_notification_iterator_destroy_cb destroy);
 221
 222 /**
 223  * Set an iterator's private data.
 224  *
 225  * @param iterator      Notification iterator instance
 226  * @param data          Iterator private data
 227  * @returns             One of #bt_notification_iterator_status values
 228  */
 229 extern enum bt_notification_iterator_status
 230 bt_notification_iterator_set_private_data(
 231                 struct bt_notification_iterator *iterator, void *data);
 232
 233 /**
 234  * Gett an iterator's private data.
 235  *
 236  * @param iterator      Notification iterator instance
 237  * @returns             Iterator instance private data
 238  */
 239 extern void *bt_notification_iterator_get_private_data(
 240                 struct bt_notification_iterator *iterator);
 241
 242 #ifdef __cplusplus
 243 }
 244 #endif
 245
 246 #endif /* BABELTRACE_PLUGIN_SYSTEM_H */