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  */
  59 typedef struct bt_component *(*bt_component_source_init_cb)(
  60                 struct bt_component *component);
  61
  62 /**
  63  * Sink component initialization function type.
  64  *
  65  * A sink component's notification handling callback, private data and
  66  * deinitialization callback must be set by this function.
  67  *
  68  * @param component     Component instance
  69  */
  70 typedef struct bt_component *(*bt_component_sink_init_cb)(
  71                 struct bt_component *component);
  72
  73 /**
  74  * Iterator initialization function type.
  75  *
  76  * @param component     Component instance
  77  * @param iterator      Iterator instance
  78  */
  79 typedef enum bt_component_status (*bt_component_source_iterator_init_cb)(
  80                 struct bt_component *component,
  81                 struct bt_notification_iterator *iterator);
  82
  83 /**
  84  * Get a component's private data.
  85  *
  86  * @param component     Component of which to get the private data
  87  * @returns             Component's private data
  88  */
  89 extern void *bt_component_get_private_data(struct bt_component *component);
  90
  91 /**
  92  * Set a component's private data.
  93  *
  94  * @param component     Component of which to set the private data
  95  * @param data          Component private data
  96  * @returns             One of #bt_component_status values
  97  */
  98 extern enum bt_component_status bt_component_set_private_data(
  99                 struct bt_component *component, void *data);
 100
 101 /**
 102  * Set a component's private data cleanup function.
 103  *
 104  * @param component     Component of which to set the private data destruction
 105  *                      function
 106  * @param data          Component private data clean-up function
 107  * @returns             One of #bt_component_status values
 108  */
 109 extern enum bt_component_status bt_component_set_destroy_cb(
 110                 struct bt_component *component,
 111                 bt_component_destroy_cb destroy);
 112
 113 /** bt_component_souce */
 114 /**
 115  * Iterator initialization function type.
 116  *
 117  * A notification iterator's private data, deinitialization, next, and get
 118  * callbacks must be set by this function.
 119  *
 120  * @param component     Component instance
 121  * @param iterator      Notification iterator instance
 122  */
 123 typedef enum bt_component_status (*bt_component_source_init_iterator_cb)(
 124                 struct bt_component *component,
 125                 struct bt_notification_iterator *iterator);
 126
 127 /**
 128  * Set a source component's iterator initialization function.
 129  *
 130  * @param component     Component instance
 131  * @param init_iterator Notification iterator initialization callback
 132  */
 133 extern enum bt_component_status
 134 bt_component_source_set_iterator_init_cb(struct bt_component *component,
 135                 bt_component_source_init_iterator_cb init_iterator);
 136
 137 /** bt_component_sink */
 138 /**
 139  * Notification handling function type.
 140  *
 141  * @param component     Component instance
 142  * @param notificattion Notification to handle
 143  * @returns             One of #bt_component_status values
 144  */
 145 typedef enum bt_component_status (*bt_component_sink_handle_notification_cb)(
 146                 struct bt_component *, struct bt_notification *);
 147
 148 /**
 149  * Set a sink component's notification handling callback.
 150  *
 151  * @param component             Component instance
 152  * @param handle_notification   Notification handling callback
 153  * @returns                     One of #bt_component_status values
 154  */
 155 extern enum bt_component_status
 156 bt_component_sink_set_handle_notification_cb(struct bt_component *component,
 157                 bt_component_sink_handle_notification_cb handle_notification);
 158
 159 /** bt_component_notification_iterator */
 160 /**
 161  * Function returning an iterator's current notification.
 162  *
 163  * @param iterator      Notification iterator instance
 164  * @returns             A notification instance
 165  */
 166 typedef struct bt_notification *(*bt_notification_iterator_get_cb)(
 167                 struct bt_notification_iterator *iterator);
 168
 169 /**
 170  * Function advancing an iterator's position.
 171  *
 172  * @param iterator      Notification iterator instance
 173  * @returns             One of #bt_notification_iterator_status values
 174  */
 175 typedef enum bt_notification_iterator_status (*bt_notification_iterator_next_cb)(
 176                 struct bt_notification_iterator *iterator);
 177
 178 /**
 179  * Function cleaning-up an iterator's private data on destruction.
 180  *
 181  * @param iterator      Notification iterator instance
 182  */
 183 typedef void (*bt_notification_iterator_destroy_cb)(
 184                 struct bt_notification_iterator *iterator);
 185
 186 extern enum bt_notification_iterator_status
 187 bt_notification_iterator_set_get_cb(struct bt_notification_iterator *iterator,
 188                 bt_notification_iterator_get_cb get);
 189
 190 extern enum bt_notification_iterator_status
 191 bt_notification_iterator_set_next_cb(struct bt_notification_iterator *iterator,
 192                 bt_notification_iterator_next_cb next);
 193
 194 extern enum bt_notification_iterator_status
 195 bt_notification_iterator_set_destroy_cb(
 196                 struct bt_notification_iterator *iterator,
 197                 bt_notification_iterator_destroy_cb destroy);
 198
 199 extern enum bt_notification_iterator_status
 200 bt_notification_iterator_set_private_data(
 201                 struct bt_notification_iterator *iterator, void *data);
 202
 203 extern void *bt_notification_iterator_get_private_data(
 204                 struct bt_notification_iterator *iterator);
 205
 206 #ifdef __cplusplus
 207 }
 208 #endif
 209
 210 #endif /* BABELTRACE_PLUGIN_SYSTEM_H */