1 #ifndef BABELTRACE_PLUGIN_SYSTEM_H
2 #define BABELTRACE_PLUGIN_SYSTEM_H
5 * BabelTrace - Babeltrace Plug-in System Interface
7 * This interface is provided for plug-ins to use the Babeltrace
8 * plug-in system facilities.
10 * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
12 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
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:
21 * The above copyright notice and this permission notice shall be included in
22 * all copies or substantial portions of the Software.
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
33 #include <babeltrace/plugin/notification/notification.h>
40 struct bt_notification
;
41 struct bt_notification_iterator
;
43 struct bt_component_factory
;
46 typedef enum bt_component_status (*bt_plugin_register_func
)(
47 struct bt_component_factory
*factory
);
50 * Component private data deallocation function type.
52 * @param component Component instance
54 typedef void (*bt_component_destroy_cb
)(struct bt_component
*component
);
57 * Component initialization function type.
59 * A component's private data and required callbacks must be set by this
62 * @param component Component instance
63 * @param params A dictionary of component parameters
64 * @returns One of #bt_component_status values
66 typedef enum bt_component_status (*bt_component_init_cb
)(
67 struct bt_component
*component
, struct bt_value
*params
);
70 * Get a component's private data.
72 * @param component Component of which to get the private data
73 * @returns Component's private data
75 extern void *bt_component_get_private_data(struct bt_component
*component
);
78 * Set a component's private data.
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
84 extern enum bt_component_status
bt_component_set_private_data(
85 struct bt_component
*component
, void *data
);
88 * Set a component's private data cleanup function.
90 * @param component Component of which to set the private data destruction
92 * @param data Component private data clean-up function
93 * @returns One of #bt_component_status values
95 extern enum bt_component_status
bt_component_set_destroy_cb(
96 struct bt_component
*component
,
97 bt_component_destroy_cb destroy
);
99 /** bt_component_souce */
101 * Iterator initialization function type.
103 * A notification iterator's private data, deinitialization, next, and get
104 * callbacks must be set by this function.
106 * @param source Source component instance
107 * @param iterator Notification iterator instance
109 typedef enum bt_component_status (*bt_component_source_init_iterator_cb
)(
110 struct bt_component
*, struct bt_notification_iterator
*);
113 * Set a source component's iterator initialization function.
115 * @param source Source component instance
116 * @param init_iterator Notification iterator initialization callback
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
);
122 /** bt_component_sink */
124 * Notification consumption function type.
126 * @param sink Sink component instance
127 * @returns One of #bt_component_status values
129 typedef enum bt_component_status (*bt_component_sink_consume_cb
)(
130 struct bt_component
*);
133 * Iterator addition function type.
135 * A sink component may choose to refuse the addition of an iterator
136 * by not returning BT_COMPONENT_STATUS_OK.
138 * @param sink Sink component instance
139 * @returns One of #bt_component_status values
141 typedef enum bt_component_status (*bt_component_sink_add_iterator_cb
)(
142 struct bt_component
*, struct bt_notification_iterator
*);
145 * Set a sink component's consumption callback.
147 * @param sink Sink component instance
148 * @param consume Consumption callback
149 * @returns One of #bt_component_status values
151 extern enum bt_component_status
152 bt_component_sink_set_consume_cb(struct bt_component
*sink
,
153 bt_component_sink_consume_cb consume
);
156 * Set a sink component's iterator addition callback.
158 * @param sink Sink component instance
159 * @param add_iterator Iterator addition callback
160 * @returns One of #bt_component_status values
162 extern enum bt_component_status
163 bt_component_sink_set_add_iterator_cb(struct bt_component
*sink
,
164 bt_component_sink_add_iterator_cb add_iterator
);
167 extern enum bt_component_status
168 bt_component_sink_set_minimum_input_count(struct bt_component
*sink
,
169 unsigned int minimum
);
172 extern enum bt_component_status
173 bt_component_sink_set_maximum_input_count(struct bt_component
*sink
,
174 unsigned int maximum
);
176 extern enum bt_component_status
177 bt_component_sink_get_input_count(struct bt_component
*sink
,
178 unsigned int *count
);
180 /* May return NULL after an interator has reached its end. */
181 extern enum bt_component_status
182 bt_component_sink_get_input_iterator(struct bt_component
*sink
,
183 unsigned int input
, struct bt_notification_iterator
**iterator
);
185 /** bt_component_filter */
187 * Iterator initialization function type.
189 * A notification iterator's private data, deinitialization, next, and get
190 * callbacks must be set by this function.
192 * @param filter Filter component instance
193 * @param iterator Notification iterator instance
195 typedef enum bt_component_status (*bt_component_filter_init_iterator_cb
)(
196 struct bt_component
*, struct bt_notification_iterator
*);
199 * Iterator addition function type.
201 * A filter component may choose to refuse the addition of an iterator
202 * by not returning BT_COMPONENT_STATUS_OK.
204 * @param filter Filter component instance
205 * @returns One of #bt_component_status values
207 typedef enum bt_component_status (*bt_component_filter_add_iterator_cb
)(
208 struct bt_component
*, struct bt_notification_iterator
*);
211 * Set a filter component's iterator initialization function.
213 * @param filter Filter component instance
214 * @param init_iterator Notification iterator initialization callback
216 extern enum bt_component_status
217 bt_component_filter_set_iterator_init_cb(struct bt_component
*filter
,
218 bt_component_filter_init_iterator_cb init_iterator
);
221 * Set a filter component's iterator addition callback.
223 * @param filter Filter component instance
224 * @param add_iterator Iterator addition callback
225 * @returns One of #bt_component_status values
227 extern enum bt_component_status
228 bt_component_filter_set_add_iterator_cb(struct bt_component
*filter
,
229 bt_component_filter_add_iterator_cb add_iterator
);
232 extern enum bt_component_status
233 bt_component_filter_set_minimum_input_count(struct bt_component
*filter
,
234 unsigned int minimum
);
237 extern enum bt_component_status
238 bt_component_filter_set_maximum_input_count(struct bt_component
*filter
,
239 unsigned int maximum
);
241 extern enum bt_component_status
242 bt_component_filter_get_input_count(struct bt_component
*filter
,
243 unsigned int *count
);
245 /* May return NULL after an interator has reached its end. */
246 extern enum bt_component_status
247 bt_component_filter_get_input_iterator(struct bt_component
*filter
,
248 unsigned int input
, struct bt_notification_iterator
**iterator
);
250 /** bt_notification_iterator */
252 * Function returning an iterator's current notification.
254 * @param iterator Notification iterator instance
255 * @returns A notification instance
257 typedef struct bt_notification
*(*bt_notification_iterator_get_cb
)(
258 struct bt_notification_iterator
*iterator
);
261 * Function advancing an iterator's position of one element.
263 * @param iterator Notification iterator instance
264 * @returns One of #bt_notification_iterator_status values
266 typedef enum bt_notification_iterator_status (*bt_notification_iterator_next_cb
)(
267 struct bt_notification_iterator
*iterator
);
270 * Function advancing an iterator's position to a given time (relative to Epoch).
272 * @param iterator Notification iterator instance
273 * @param time Time at which to seek, expressed in ns since Epoch
274 * @returns One of #bt_notification_iterator_status values
276 typedef enum bt_notification_iterator_status
277 (*bt_notification_iterator_seek_time_cb
)(
278 struct bt_notification_iterator
*iterator
, int64_t time
);
281 * Function cleaning-up an iterator's private data on destruction.
283 * @param iterator Notification iterator instance
285 typedef void (*bt_notification_iterator_destroy_cb
)(
286 struct bt_notification_iterator
*iterator
);
289 * Set an iterator's "get" callback which return the current notification.
291 * @param iterator Notification iterator instance
292 * @param get Notification return callback
293 * @returns One of #bt_notification_iterator_status values
295 extern enum bt_notification_iterator_status
296 bt_notification_iterator_set_get_cb(struct bt_notification_iterator
*iterator
,
297 bt_notification_iterator_get_cb get
);
300 * Set an iterator's "next" callback which advances the iterator's position.
302 * @param iterator Notification iterator instance
303 * @param next Iterator "next" callback
304 * @returns One of #bt_notification_iterator_status values
306 extern enum bt_notification_iterator_status
307 bt_notification_iterator_set_next_cb(struct bt_notification_iterator
*iterator
,
308 bt_notification_iterator_next_cb next
);
311 * Set an iterator's "seek_time" callback which sets the iterator's position to
312 * provided time (in ns since Epoch).
314 * @param iterator Notification iterator instance
315 * @param seek_timetime Iterator "seek_time" callback
316 * @returns One of #bt_notification_iterator_status values
318 extern enum bt_notification_iterator_status
319 bt_notification_iterator_set_seek_time_cb(struct bt_notification_iterator
*iterator
,
320 bt_notification_iterator_seek_time_cb seek_time
);
323 * Set an iterator's "destroy" callback.
325 * @param iterator Notification iterator instance
326 * @param next Iterator destruction callback
327 * @returns One of #bt_notification_iterator_status values
329 extern enum bt_notification_iterator_status
330 bt_notification_iterator_set_destroy_cb(
331 struct bt_notification_iterator
*iterator
,
332 bt_notification_iterator_destroy_cb destroy
);
335 * Set an iterator's private data.
337 * @param iterator Notification iterator instance
338 * @param data Iterator private data
339 * @returns One of #bt_notification_iterator_status values
341 extern enum bt_notification_iterator_status
342 bt_notification_iterator_set_private_data(
343 struct bt_notification_iterator
*iterator
, void *data
);
346 * Get an iterator's private data.
348 * @param iterator Notification iterator instance
349 * @returns Iterator instance private data
351 extern void *bt_notification_iterator_get_private_data(
352 struct bt_notification_iterator
*iterator
);
358 #endif /* BABELTRACE_PLUGIN_SYSTEM_H */