Commit | Line | Data |
---|---|---|
43c59509 | 1 | /* |
0235b0db | 2 | * SPDX-License-Identifier: MIT |
43c59509 | 3 | * |
0235b0db | 4 | * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation |
43c59509 PP |
5 | */ |
6 | ||
0235b0db MJ |
7 | #ifndef BABELTRACE2_PLUGIN_PLUGIN_LOADING_H |
8 | #define BABELTRACE2_PLUGIN_PLUGIN_LOADING_H | |
9 | ||
f38da6ca SM |
10 | /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */ |
11 | ||
43c59509 PP |
12 | #ifndef __BT_IN_BABELTRACE_H |
13 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
14 | #endif | |
15 | ||
16 | #include <stdint.h> | |
17 | #include <stddef.h> | |
18 | ||
19 | #include <babeltrace2/types.h> | |
20 | ||
21 | #ifdef __cplusplus | |
22 | extern "C" { | |
23 | #endif | |
24 | ||
25 | /*! | |
26 | @defgroup api-plugin Plugin loading | |
27 | ||
28 | @brief | |
29 | Plugin loading functions. | |
30 | ||
31 | A <strong><em>plugin</em></strong> is a package of \bt_p_comp_cls: | |
32 | ||
33 | @image html plugin.png "A plugin is a package of component classes." | |
34 | ||
35 | @attention | |
36 | The plugin loading API offers functions to <em>find and load</em> | |
37 | existing plugins and use the packaged \bt_p_comp_cls. To \em write a | |
38 | plugin, see \ref api-plugin-dev. | |
39 | ||
40 | There are three types of plugins: | |
41 | ||
42 | <dl> | |
43 | <dt>Shared object plugin</dt> | |
44 | <dd> | |
45 | <code>.so</code> file on Unix systems; | |
46 | <code>.dll</code> file on Windows systems. | |
47 | </dd> | |
48 | ||
49 | <dt>Python 3 plugin</dt> | |
50 | <dd> | |
51 | <code>.py</code> file which starts with the | |
52 | <code>bt_plugin_</code> prefix. | |
53 | </dd> | |
54 | ||
55 | <dt>Static plugin</dt> | |
56 | <dd> | |
57 | A plugin built directly into libbabeltrace2 or into the | |
58 | user application. | |
59 | </dd> | |
60 | </dl> | |
61 | ||
62 | libbabeltrace2 loads shared object and Python plugins. Those plugins | |
63 | need libbabeltrace2 in turn to create and use \bt_name objects: | |
64 | ||
65 | @image html linking.png "libbabeltrace2 loads plugins which need libbabeltrace2." | |
66 | ||
67 | A plugin is a \ref api-fund-shared-object "shared object": get a new | |
68 | reference with bt_plugin_get_ref() and put an existing reference with | |
69 | bt_plugin_put_ref(). | |
70 | ||
71 | Get the number of \bt_comp_cls in a plugin with | |
72 | bt_plugin_get_source_component_class_count(), | |
73 | bt_plugin_get_filter_component_class_count(), and | |
74 | bt_plugin_get_sink_component_class_count(). | |
75 | ||
76 | Borrow a \bt_comp_cls by index from a plugin with | |
77 | bt_plugin_borrow_source_component_class_by_index_const(), | |
78 | bt_plugin_borrow_filter_component_class_by_index_const(), and | |
79 | bt_plugin_borrow_sink_component_class_by_index_const(). | |
80 | ||
81 | Borrow a \bt_comp_cls by name from a plugin with | |
82 | bt_plugin_borrow_source_component_class_by_name_const(), | |
83 | bt_plugin_borrow_filter_component_class_by_name_const(), and | |
84 | bt_plugin_borrow_sink_component_class_by_name_const(). | |
85 | ||
86 | The bt_plugin_find_all(), bt_plugin_find_all_from_file(), | |
87 | bt_plugin_find_all_from_dir(), and bt_plugin_find_all_from_static() | |
88 | functions return a <strong>plugin set</strong>, that is, a shared object | |
89 | containing one or more plugins. | |
90 | ||
91 | <h1>Find and load plugins</h1> | |
92 | ||
93 | \anchor api-plugin-def-dirs The bt_plugin_find() and | |
94 | bt_plugin_find_all() functions find and load plugins from the default | |
95 | plugin search directories and from the static plugins. | |
96 | ||
97 | The plugin search order is: | |
98 | ||
99 | -# The colon-separated (or semicolon-separated on Windows) list of | |
100 | directories in the \c BABELTRACE_PLUGIN_PATH environment variable, | |
101 | if it's set. | |
102 | ||
103 | The function searches each directory in this list, without recursing. | |
104 | ||
105 | -# <code>$HOME/.local/lib/babeltrace2/plugins</code>, | |
106 | without recursing. | |
107 | ||
108 | -# The system \bt_name plugin directory, typically | |
109 | <code>/usr/lib/babeltrace2/plugins</code> or | |
110 | <code>/usr/local/lib/babeltrace2/plugins</code> on Linux, | |
111 | without recursing. | |
112 | ||
113 | -# The static plugins. | |
114 | ||
115 | Both bt_plugin_find() and bt_plugin_find_all() functions have dedicated | |
116 | boolean parameters to include or exclude each of the four locations | |
117 | above. | |
118 | ||
119 | <h2>Find and load a plugin by name</h2> | |
120 | ||
121 | Find and load a plugin by name with bt_plugin_find(). | |
122 | ||
123 | bt_plugin_find() tries to find a plugin with a specific name within | |
124 | the \ref api-plugin-def-dirs "default plugin search directories" | |
125 | and static plugins. | |
126 | ||
127 | <h2>Find and load all the plugins from the default directories</h2> | |
128 | ||
129 | Load all the plugins found in the | |
130 | \ref api-plugin-def-dirs "default plugin search directories" | |
131 | and static plugins with bt_plugin_find_all(). | |
132 | ||
133 | <h2>Find and load plugins from a specific file or directory</h2> | |
134 | ||
135 | Find and load plugins from a specific file (<code>.so</code>, | |
136 | <code>.dll</code>, or <code>.py</code>) with | |
137 | bt_plugin_find_all_from_file(). | |
138 | ||
139 | A single shared object file can contain multiple plugins, although it's | |
140 | not common practice to do so. | |
141 | ||
142 | Find and load plugins from a specific directory with | |
143 | bt_plugin_find_all_from_dir(). This function can search for plugins | |
144 | within the given directory recursively or not. | |
145 | ||
146 | <h2>Find and load static plugins</h2> | |
147 | ||
148 | Find and load static plugins with bt_plugin_find_all_from_static(). | |
149 | ||
150 | A static plugin is built directly into the application or library | |
151 | instead of being a separate shared object file. | |
152 | ||
153 | <h1>Plugin properties</h1> | |
154 | ||
155 | A plugin has the following properties: | |
156 | ||
157 | <dl> | |
158 | <dt> | |
159 | \anchor api-plugin-prop-name | |
160 | Name | |
161 | </dt> | |
162 | <dd> | |
163 | Name of the plugin. | |
164 | ||
165 | The plugin's name is not related to its file name. For example, | |
166 | a plugin found in the file \c patente.so can be named | |
167 | <code>Dan</code>. | |
168 | ||
169 | Use bt_plugin_get_name(). | |
170 | </dd> | |
171 | ||
172 | <dt> | |
173 | \anchor api-plugin-prop-descr | |
174 | \bt_dt_opt Description | |
175 | </dt> | |
176 | <dd> | |
177 | Description of the plugin. | |
178 | ||
179 | Use bt_plugin_get_description(). | |
180 | </dd> | |
181 | ||
182 | <dt> | |
183 | \anchor api-plugin-prop-author | |
184 | \bt_dt_opt Author name(s) | |
185 | </dt> | |
186 | <dd> | |
187 | Name(s) of the plugin's author(s). | |
188 | ||
189 | Use bt_plugin_get_author(). | |
190 | </dd> | |
191 | ||
192 | <dt> | |
193 | \anchor api-plugin-prop-license | |
194 | \bt_dt_opt License | |
195 | </dt> | |
196 | <dd> | |
197 | License or license name of the plugin. | |
198 | ||
199 | Use bt_plugin_get_license(). | |
200 | </dd> | |
201 | ||
202 | <dt> | |
203 | \anchor api-plugin-prop-path | |
204 | \bt_dt_opt Path | |
205 | </dt> | |
206 | <dd> | |
207 | Path of the file which contains the plugin. | |
208 | ||
209 | A static plugin has no path property. | |
210 | ||
211 | Get bt_plugin_get_path(). | |
212 | </dd> | |
213 | ||
214 | <dt> | |
215 | \anchor api-plugin-prop-version | |
216 | \bt_dt_opt Version | |
217 | </dt> | |
218 | <dd> | |
219 | Version of the plugin (major, minor, patch, and extra information). | |
220 | ||
221 | The plugin's version is completely user-defined: the library does | |
222 | not use this property in any way to verify the plugin's | |
223 | compatibility. | |
224 | ||
225 | Use bt_plugin_get_version(). | |
226 | </dd> | |
227 | </dl> | |
228 | */ | |
229 | ||
230 | /*! @{ */ | |
231 | ||
232 | /*! | |
233 | @name Type | |
234 | @{ | |
235 | ||
236 | @typedef struct bt_plugin bt_plugin; | |
237 | ||
238 | @brief | |
239 | Plugin. | |
240 | ||
43c59509 PP |
241 | @typedef struct bt_plugin_set bt_plugin_set; |
242 | ||
243 | @brief | |
244 | Set of plugins. | |
245 | ||
246 | @} | |
247 | */ | |
248 | ||
249 | /*! | |
250 | @name Find and load plugins | |
251 | @{ | |
252 | */ | |
253 | ||
254 | /*! | |
255 | @brief | |
256 | Status codes for bt_plugin_find(). | |
257 | */ | |
258 | typedef enum bt_plugin_find_status { | |
259 | /*! | |
260 | @brief | |
261 | Success. | |
262 | */ | |
263 | BT_PLUGIN_FIND_STATUS_OK = __BT_FUNC_STATUS_OK, | |
264 | ||
265 | /*! | |
266 | @brief | |
267 | Plugin not found. | |
268 | */ | |
269 | BT_PLUGIN_FIND_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND, | |
270 | ||
271 | /*! | |
272 | @brief | |
273 | Out of memory. | |
274 | */ | |
275 | BT_PLUGIN_FIND_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
276 | ||
277 | /*! | |
278 | @brief | |
279 | Error. | |
280 | */ | |
281 | BT_PLUGIN_FIND_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
282 | } bt_plugin_find_status; | |
283 | ||
284 | /*! | |
285 | @brief | |
286 | Finds and loads a single plugin which has the name | |
287 | \bt_p{plugin_name} from the default plugin search directories and | |
288 | static plugins, setting \bt_p{*plugin} to the result. | |
289 | ||
290 | This function returns the first plugin which has the name | |
291 | \bt_p{plugin_name} within, in order: | |
292 | ||
293 | -# <strong>If the \bt_p{find_in_std_env_var} parameter is | |
294 | #BT_TRUE</strong>, | |
295 | the colon-separated (or semicolon-separated on Windows) list of | |
296 | directories in the \c BABELTRACE_PLUGIN_PATH environment variable, | |
297 | if it's set. | |
298 | ||
299 | The function searches each directory in this list, without recursing. | |
300 | ||
301 | -# <strong>If the \bt_p{find_in_user_dir} parameter is | |
302 | #BT_TRUE</strong>, <code>$HOME/.local/lib/babeltrace2/plugins</code>, | |
303 | without recursing. | |
304 | ||
305 | -# <strong>If the \bt_p{find_in_sys_dir} is #BT_TRUE</strong>, the | |
306 | system \bt_name plugin directory, typically | |
307 | <code>/usr/lib/babeltrace2/plugins</code> or | |
308 | <code>/usr/local/lib/babeltrace2/plugins</code> on Linux, without | |
309 | recursing. | |
310 | ||
311 | -# <strong>If the \bt_p{find_in_static} is #BT_TRUE</strong>, | |
312 | the static plugins. | |
313 | ||
314 | @note | |
315 | A plugin's name is not related to the name of its file (shared | |
316 | object or Python file). For example, a plugin found in the file | |
317 | \c patente.so can be named <code>Dan</code>. | |
318 | ||
319 | If this function finds a file which looks like a plugin (shared object | |
320 | file or Python file with the \c bt_plugin_ prefix), but it fails to load | |
321 | it for any reason, the function: | |
322 | ||
323 | <dl> | |
324 | <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt> | |
325 | <dd>Returns #BT_PLUGIN_FIND_STATUS_ERROR.</dd> | |
326 | ||
327 | <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt> | |
328 | <dd>Ignores the loading error and continues searching.</dd> | |
329 | </dl> | |
330 | ||
331 | If this function doesn't find any plugin, it returns | |
332 | #BT_PLUGIN_FIND_STATUS_NOT_FOUND and does \em not set \bt_p{*plugin}. | |
333 | ||
334 | @param[in] plugin_name | |
335 | Name of the plugin to find and load. | |
336 | @param[in] find_in_std_env_var | |
337 | #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in the | |
338 | colon-separated (or semicolon-separated on Windows) list of | |
339 | directories in the \c BABELTRACE_PLUGIN_PATH environment variable. | |
340 | @param[in] find_in_user_dir | |
341 | #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in | |
342 | the <code>$HOME/.local/lib/babeltrace2/plugins</code> directory, | |
343 | without recursing. | |
344 | @param[in] find_in_sys_dir | |
345 | #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in | |
346 | the system \bt_name plugin directory. | |
347 | @param[in] find_in_static | |
348 | #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in the | |
349 | static plugins. | |
350 | @param[in] fail_on_load_error | |
351 | #BT_TRUE to make this function return #BT_PLUGIN_FIND_STATUS_ERROR | |
352 | on any plugin loading error instead of ignoring it. | |
353 | @param[out] plugin | |
354 | <strong>On success</strong>, \bt_p{*plugin} is a new plugin | |
355 | reference of named \bt_p{plugin_name}. | |
356 | ||
357 | @retval #BT_PLUGIN_FIND_STATUS_OK | |
358 | Success. | |
359 | @retval #BT_PLUGIN_FIND_STATUS_NOT_FOUND | |
360 | Plugin not found. | |
361 | @retval #BT_PLUGIN_FIND_STATUS_MEMORY_ERROR | |
362 | Out of memory. | |
363 | @retval #BT_PLUGIN_FIND_STATUS_ERROR | |
364 | Error. | |
365 | ||
366 | @bt_pre_not_null{plugin_name} | |
367 | @pre | |
368 | At least one of the \bt_p{find_in_std_env_var}, | |
369 | \bt_p{find_in_user_dir}, \bt_p{find_in_sys_dir}, and | |
370 | \bt_p{find_in_static} parameters is #BT_TRUE. | |
371 | @bt_pre_not_null{plugin} | |
372 | ||
373 | @sa bt_plugin_find_all() — | |
374 | Finds and loads all plugins from the default plugin search | |
375 | directories and static plugins. | |
376 | */ | |
377 | extern bt_plugin_find_status bt_plugin_find(const char *plugin_name, | |
378 | bt_bool find_in_std_env_var, bt_bool find_in_user_dir, | |
379 | bt_bool find_in_sys_dir, bt_bool find_in_static, | |
380 | bt_bool fail_on_load_error, const bt_plugin **plugin); | |
381 | ||
382 | /*! | |
383 | @brief | |
384 | Status codes for bt_plugin_find_all(). | |
385 | */ | |
386 | typedef enum bt_plugin_find_all_status { | |
387 | /*! | |
388 | @brief | |
389 | Success. | |
390 | */ | |
391 | BT_PLUGIN_FIND_ALL_STATUS_OK = __BT_FUNC_STATUS_OK, | |
392 | ||
393 | /*! | |
394 | @brief | |
395 | No plugins found. | |
396 | */ | |
397 | BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND, | |
398 | ||
399 | /*! | |
400 | @brief | |
401 | Out of memory. | |
402 | */ | |
403 | BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
404 | ||
405 | /*! | |
406 | @brief | |
407 | Error. | |
408 | */ | |
409 | BT_PLUGIN_FIND_ALL_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
410 | } bt_plugin_find_all_status; | |
411 | ||
412 | /*! | |
413 | @brief | |
414 | Finds and loads all the plugins from the default | |
415 | plugin search directories and static plugins, setting | |
416 | \bt_p{*plugins} to the result. | |
417 | ||
418 | This function returns all the plugins within, in order: | |
419 | ||
420 | -# <strong>If the \bt_p{find_in_std_env_var} parameter is | |
421 | #BT_TRUE</strong>, | |
422 | the colon-separated (or semicolon-separated on Windows) list of | |
423 | directories in the \c BABELTRACE_PLUGIN_PATH environment variable, | |
424 | if it's set. | |
425 | ||
426 | The function searches each directory in this list, without recursing. | |
427 | ||
428 | -# <strong>If the \bt_p{find_in_user_dir} parameter is | |
429 | #BT_TRUE</strong>, <code>$HOME/.local/lib/babeltrace2/plugins</code>, | |
430 | without recursing. | |
431 | ||
432 | -# <strong>If the \bt_p{find_in_sys_dir} is #BT_TRUE</strong>, the | |
433 | system \bt_name plugin directory, typically | |
434 | <code>/usr/lib/babeltrace2/plugins</code> or | |
435 | <code>/usr/local/lib/babeltrace2/plugins</code> on Linux, without | |
436 | recursing. | |
437 | ||
438 | -# <strong>If the \bt_p{find_in_static} is #BT_TRUE</strong>, | |
439 | the static plugins. | |
440 | ||
441 | During the search process, if a found plugin shares the name of an | |
442 | already loaded plugin, this function ignores it and continues. | |
443 | ||
444 | If this function finds a file which looks like a plugin (shared object | |
445 | file or Python file with the \c bt_plugin_ prefix), but it fails to load | |
446 | it for any reason, the function: | |
447 | ||
448 | <dl> | |
449 | <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt> | |
450 | <dd>Returns #BT_PLUGIN_FIND_ALL_STATUS_ERROR.</dd> | |
451 | ||
452 | <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt> | |
453 | <dd>Ignores the loading error and continues searching.</dd> | |
454 | </dl> | |
455 | ||
456 | If this function doesn't find any plugin, it returns | |
457 | #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND and does \em not set | |
458 | \bt_p{*plugins}. | |
459 | ||
460 | @param[in] find_in_std_env_var | |
461 | #BT_TRUE to try to find all the plugins in the | |
462 | colon-separated (or semicolon-separated on Windows) list of | |
463 | directories in the \c BABELTRACE_PLUGIN_PATH environment variable. | |
464 | @param[in] find_in_user_dir | |
465 | #BT_TRUE to try to find all the plugins in | |
466 | the <code>$HOME/.local/lib/babeltrace2/plugins</code> directory, | |
467 | without recursing. | |
468 | @param[in] find_in_sys_dir | |
469 | #BT_TRUE to try to find all the plugins in the system \bt_name | |
470 | plugin directory. | |
471 | @param[in] find_in_static | |
472 | #BT_TRUE to try to find all the plugins in the static plugins. | |
473 | @param[in] fail_on_load_error | |
474 | #BT_TRUE to make this function return | |
475 | #BT_PLUGIN_FIND_ALL_STATUS_ERROR on any plugin loading error instead | |
476 | of ignoring it. | |
477 | @param[out] plugins | |
478 | <strong>On success</strong>, \bt_p{*plugins} is a new plugin set | |
479 | reference which contains all the plugins found from the default | |
480 | plugin search directories and static plugins. | |
481 | ||
482 | @retval #BT_PLUGIN_FIND_ALL_STATUS_OK | |
483 | Success. | |
484 | @retval #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND | |
485 | No plugins found. | |
486 | @retval #BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR | |
487 | Out of memory. | |
488 | @retval #BT_PLUGIN_FIND_ALL_STATUS_ERROR | |
489 | Error. | |
490 | ||
491 | @pre | |
492 | At least one of the \bt_p{find_in_std_env_var}, | |
493 | \bt_p{find_in_user_dir}, \bt_p{find_in_sys_dir}, and | |
494 | \bt_p{find_in_static} parameters is #BT_TRUE. | |
495 | @bt_pre_not_null{plugins} | |
496 | ||
497 | @sa bt_plugin_find() — | |
498 | Finds and loads a single plugin by name from the default plugin search | |
499 | directories and static plugins. | |
500 | */ | |
501 | bt_plugin_find_all_status bt_plugin_find_all(bt_bool find_in_std_env_var, | |
502 | bt_bool find_in_user_dir, bt_bool find_in_sys_dir, | |
503 | bt_bool find_in_static, bt_bool fail_on_load_error, | |
504 | const bt_plugin_set **plugins); | |
505 | ||
506 | /*! | |
507 | @brief | |
508 | Status codes for bt_plugin_find_all_from_file(). | |
509 | */ | |
510 | typedef enum bt_plugin_find_all_from_file_status { | |
511 | /*! | |
512 | @brief | |
513 | Success. | |
514 | */ | |
515 | BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK = __BT_FUNC_STATUS_OK, | |
516 | ||
517 | /*! | |
518 | @brief | |
519 | No plugins found. | |
520 | */ | |
521 | BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND, | |
522 | ||
523 | /*! | |
524 | @brief | |
525 | Out of memory. | |
526 | */ | |
527 | BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
528 | ||
529 | /*! | |
530 | @brief | |
531 | Error. | |
532 | */ | |
533 | BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
534 | } bt_plugin_find_all_from_file_status; | |
535 | ||
536 | /*! | |
537 | @brief | |
538 | Finds and loads all the plugins from the file with path \bt_p{path}, | |
539 | setting \bt_p{*plugins} to the result. | |
540 | ||
541 | @note | |
542 | A plugin's name is not related to the name of its file (shared | |
543 | object or Python file). For example, a plugin found in the file | |
544 | \c patente.so can be named <code>Dan</code>. | |
545 | ||
546 | If any plugin loading error occurs during this function's execution, the | |
547 | function: | |
548 | ||
549 | <dl> | |
550 | <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt> | |
551 | <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR.</dd> | |
552 | ||
553 | <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt> | |
554 | <dd>Ignores the loading error and continues.</dd> | |
555 | </dl> | |
556 | ||
557 | If this function doesn't find any plugin, it returns | |
558 | #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND and does \em not set | |
559 | \bt_p{*plugins}. | |
560 | ||
561 | @param[in] path | |
562 | Path of the file in which to find and load all the plugins. | |
563 | @param[in] fail_on_load_error | |
564 | #BT_TRUE to make this function return | |
565 | #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR on any plugin loading | |
566 | error instead of ignoring it. | |
567 | @param[out] plugins | |
568 | <strong>On success</strong>, \bt_p{*plugins} is a new plugin set | |
569 | reference which contains all the plugins found in the file with path | |
570 | \bt_p{path}. | |
571 | ||
572 | @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK | |
573 | Success. | |
574 | @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND | |
575 | No plugins found. | |
576 | @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR | |
577 | Out of memory. | |
578 | @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR | |
579 | Error. | |
580 | ||
581 | @bt_pre_not_null{path} | |
582 | @pre | |
583 | \bt_p{path} is the path of a regular file. | |
584 | @bt_pre_not_null{plugins} | |
585 | ||
586 | @sa bt_plugin_find_all_from_dir() — | |
587 | Finds and loads all plugins from a given directory. | |
588 | */ | |
589 | extern bt_plugin_find_all_from_file_status bt_plugin_find_all_from_file( | |
590 | const char *path, bt_bool fail_on_load_error, | |
591 | const bt_plugin_set **plugins); | |
592 | ||
593 | /*! | |
594 | @brief | |
595 | Status codes for bt_plugin_find_all_from_dir(). | |
596 | */ | |
597 | typedef enum bt_plugin_find_all_from_dir_status { | |
598 | /*! | |
599 | @brief | |
600 | Success. | |
601 | */ | |
602 | BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK = __BT_FUNC_STATUS_OK, | |
603 | ||
604 | /*! | |
605 | @brief | |
606 | No plugins found. | |
607 | */ | |
608 | BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND, | |
609 | ||
610 | /*! | |
611 | @brief | |
612 | Out of memory. | |
613 | */ | |
614 | BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
615 | ||
616 | /*! | |
617 | @brief | |
618 | Error. | |
619 | */ | |
620 | BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
621 | } bt_plugin_find_all_from_dir_status; | |
622 | ||
623 | /*! | |
624 | @brief | |
625 | Finds and loads all the plugins from the directory with path | |
626 | \bt_p{path}, setting \bt_p{*plugins} to the result. | |
627 | ||
628 | If \bt_p{recurse} is #BT_TRUE, this function recurses into the | |
629 | subdirectories of \bt_p{path} to find plugins. | |
630 | ||
631 | During the search process, if a found plugin shares the name of an | |
632 | already loaded plugin, this function ignores it and continues. | |
633 | ||
634 | @attention | |
635 | As of \bt_name_version_min_maj, the file and directory traversal | |
636 | order is undefined. | |
637 | ||
638 | If any plugin loading error occurs during this function's execution, the | |
639 | function: | |
640 | ||
641 | <dl> | |
642 | <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt> | |
643 | <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR.</dd> | |
644 | ||
645 | <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt> | |
646 | <dd>Ignores the loading error and continues.</dd> | |
647 | </dl> | |
648 | ||
649 | If this function doesn't find any plugin, it returns | |
650 | #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND and does \em not set | |
651 | \bt_p{*plugins}. | |
652 | ||
653 | @param[in] path | |
654 | Path of the directory in which to find and load all the plugins. | |
655 | @param[in] recurse | |
656 | #BT_TRUE to make this function recurse into the subdirectories | |
657 | of \bt_p{path}. | |
658 | @param[in] fail_on_load_error | |
659 | #BT_TRUE to make this function return | |
660 | #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR on any plugin loading | |
661 | error instead of ignoring it. | |
662 | @param[out] plugins | |
663 | <strong>On success</strong>, \bt_p{*plugins} is a new plugin set | |
664 | reference which contains all the plugins found in the directory with | |
665 | path \bt_p{path}. | |
666 | ||
667 | @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK | |
668 | Success. | |
669 | @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND | |
670 | No plugins found. | |
671 | @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR | |
672 | Out of memory. | |
673 | @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR | |
674 | Error. | |
675 | ||
676 | @bt_pre_not_null{path} | |
677 | @pre | |
678 | \bt_p{path} is the path of a directory. | |
679 | @bt_pre_not_null{plugins} | |
680 | ||
681 | @sa bt_plugin_find_all_from_file() — | |
682 | Finds and loads all plugins from a given file. | |
683 | */ | |
684 | extern bt_plugin_find_all_from_dir_status bt_plugin_find_all_from_dir( | |
685 | const char *path, bt_bool recurse, bt_bool fail_on_load_error, | |
686 | const bt_plugin_set **plugins); | |
687 | ||
688 | /*! | |
689 | @brief | |
690 | Status codes for bt_plugin_find_all_from_static(). | |
691 | */ | |
692 | typedef enum bt_plugin_find_all_from_static_status { | |
693 | /*! | |
694 | @brief | |
695 | Success. | |
696 | */ | |
697 | BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK = __BT_FUNC_STATUS_OK, | |
698 | ||
699 | /*! | |
700 | @brief | |
701 | No static plugins found. | |
702 | */ | |
703 | BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND, | |
704 | ||
705 | /*! | |
706 | @brief | |
707 | Out of memory. | |
708 | */ | |
709 | BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
710 | ||
711 | /*! | |
712 | @brief | |
713 | Error. | |
714 | */ | |
715 | BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
716 | } bt_plugin_find_all_from_static_status; | |
717 | ||
718 | /*! | |
719 | @brief | |
720 | Finds and loads all the static plugins, | |
721 | setting \bt_p{*plugins} to the result. | |
722 | ||
723 | A static plugin is built directly into the application or library | |
724 | instead of being a separate shared object file. | |
725 | ||
726 | If any plugin loading error occurs during this function's execution, the | |
727 | function: | |
728 | ||
729 | <dl> | |
730 | <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt> | |
731 | <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR.</dd> | |
732 | ||
733 | <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt> | |
734 | <dd>Ignores the loading error and continues.</dd> | |
735 | </dl> | |
736 | ||
737 | If this function doesn't find any plugin, it returns | |
738 | #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND and does \em not set | |
739 | \bt_p{*plugins}. | |
740 | ||
741 | @param[in] fail_on_load_error | |
742 | #BT_TRUE to make this function return | |
743 | #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR on any plugin loading | |
744 | error instead of ignoring it. | |
745 | @param[out] plugins | |
746 | <strong>On success</strong>, \bt_p{*plugins} is a new plugin set | |
747 | reference which contains all the static plugins. | |
748 | ||
749 | @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK | |
750 | Success. | |
751 | @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND | |
752 | No static plugins found. | |
753 | @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR | |
754 | Out of memory. | |
755 | @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR | |
756 | Error. | |
757 | ||
758 | @bt_pre_not_null{path} | |
759 | @bt_pre_not_null{plugins} | |
760 | */ | |
761 | extern bt_plugin_find_all_from_static_status bt_plugin_find_all_from_static( | |
762 | bt_bool fail_on_load_error, const bt_plugin_set **plugins); | |
763 | ||
764 | /*! @} */ | |
765 | ||
766 | /*! | |
767 | @name Plugin properties | |
768 | @{ | |
769 | */ | |
770 | ||
771 | /*! | |
772 | @brief | |
773 | Returns the name of the plugin \bt_p{plugin}. | |
774 | ||
775 | See the \ref api-plugin-prop-name "name" property. | |
776 | ||
777 | @param[in] plugin | |
778 | Plugin of which to get the name. | |
779 | ||
780 | @returns | |
781 | @parblock | |
782 | Name of \bt_p{plugin}. | |
783 | ||
784 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
785 | @endparblock | |
786 | ||
787 | @bt_pre_not_null{plugin} | |
788 | */ | |
789 | extern const char *bt_plugin_get_name(const bt_plugin *plugin); | |
790 | ||
791 | /*! | |
792 | @brief | |
793 | Returns the description of the plugin \bt_p{plugin}. | |
794 | ||
795 | See the \ref api-plugin-prop-descr "description" property. | |
796 | ||
797 | @param[in] plugin | |
798 | Plugin of which to get description. | |
799 | ||
800 | @returns | |
801 | @parblock | |
802 | Description of \bt_p{plugin}, or \c NULL if not available. | |
803 | ||
804 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
805 | @endparblock | |
806 | ||
807 | @bt_pre_not_null{plugin} | |
808 | */ | |
809 | extern const char *bt_plugin_get_description(const bt_plugin *plugin); | |
810 | ||
811 | /*! | |
812 | @brief | |
813 | Returns the name(s) of the author(s) of the plugin \bt_p{plugin}. | |
814 | ||
815 | See the \ref api-plugin-prop-author "author name(s)" property. | |
816 | ||
817 | @param[in] plugin | |
818 | Plugin of which to get the author name(s). | |
819 | ||
820 | @returns | |
821 | @parblock | |
822 | Author name(s) of \bt_p{plugin}, or \c NULL if not available. | |
823 | ||
824 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
825 | @endparblock | |
826 | ||
827 | @bt_pre_not_null{plugin} | |
828 | */ | |
829 | extern const char *bt_plugin_get_author(const bt_plugin *plugin); | |
830 | ||
831 | /*! | |
832 | @brief | |
833 | Returns the license text or the license name of the plugin | |
834 | \bt_p{plugin}. | |
835 | ||
836 | See the \ref api-plugin-prop-license "license" property. | |
837 | ||
838 | @param[in] plugin | |
839 | Plugin of which to get the license. | |
840 | ||
841 | @returns | |
842 | @parblock | |
843 | License of \bt_p{plugin}, or \c NULL if not available. | |
844 | ||
845 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
846 | @endparblock | |
847 | ||
848 | @bt_pre_not_null{plugin} | |
849 | */ | |
850 | extern const char *bt_plugin_get_license(const bt_plugin *plugin); | |
851 | ||
852 | /*! | |
853 | @brief | |
854 | Returns the path of the file which contains the plugin | |
855 | \bt_p{plugin}. | |
856 | ||
857 | See the \ref api-plugin-prop-path "path" property. | |
858 | ||
859 | This function returns \c NULL if \bt_p{plugin} is a static plugin | |
860 | because a static plugin has no path property. | |
861 | ||
862 | @param[in] plugin | |
863 | Plugin of which to get the containing file's path. | |
864 | ||
865 | @returns | |
866 | @parblock | |
867 | Path of the file which contains \bt_p{plugin}, or \c NULL if | |
868 | not available. | |
869 | ||
870 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
871 | @endparblock | |
872 | ||
873 | @bt_pre_not_null{plugin} | |
874 | */ | |
875 | extern const char *bt_plugin_get_path(const bt_plugin *plugin); | |
876 | ||
877 | /*! | |
878 | @brief | |
879 | Returns the version of the plugin \bt_p{plugin}. | |
880 | ||
881 | See the \ref api-plugin-prop-version "version" property. | |
882 | ||
883 | @param[in] plugin | |
884 | Plugin of which to get the version. | |
885 | @param[out] major | |
886 | <strong>If not \c NULL and this function returns | |
887 | #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*major} is the | |
888 | major version of \bt_p{plugin}. | |
889 | @param[out] minor | |
890 | <strong>If not \c NULL and this function returns | |
891 | #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*minor} is the | |
892 | minor version of \bt_p{plugin}. | |
893 | @param[out] patch | |
894 | <strong>If not \c NULL and this function returns | |
895 | #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*patch} is the | |
896 | patch version of \bt_p{plugin}. | |
897 | @param[out] extra | |
898 | @parblock | |
899 | <strong>If not \c NULL and this function returns | |
900 | #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*extra} is the | |
901 | version's extra information of \bt_p{plugin}. | |
902 | ||
903 | \bt_p{*extra} can be \c NULL if the plugin's version has no extra | |
904 | information. | |
905 | ||
906 | \bt_p{*extra} remains valid as long as \bt_p{plugin} exists. | |
907 | @endparblock | |
908 | ||
909 | @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE | |
910 | The version of \bt_p{plugin} is available. | |
911 | @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE | |
912 | The version of \bt_p{plugin} is not available. | |
913 | ||
914 | @bt_pre_not_null{plugin} | |
915 | */ | |
916 | extern bt_property_availability bt_plugin_get_version( | |
917 | const bt_plugin *plugin, unsigned int *major, | |
918 | unsigned int *minor, unsigned int *patch, const char **extra); | |
919 | ||
920 | /*! @} */ | |
921 | ||
922 | /*! | |
923 | @name Plugin component class access | |
924 | @{ | |
925 | */ | |
926 | ||
927 | /*! | |
928 | @brief | |
929 | Returns the number of source component classes contained in the | |
930 | plugin \bt_p{plugin}. | |
931 | ||
932 | @param[in] plugin | |
933 | Plugin of which to get the number of contained source | |
934 | component classes. | |
935 | ||
936 | @returns | |
937 | Number of contained source component classes in \bt_p{plugin}. | |
938 | ||
939 | @bt_pre_not_null{plugin} | |
940 | */ | |
941 | extern uint64_t bt_plugin_get_source_component_class_count( | |
942 | const bt_plugin *plugin); | |
943 | ||
944 | /*! | |
945 | @brief | |
946 | Returns the number of filter component classes contained in the | |
947 | plugin \bt_p{plugin}. | |
948 | ||
949 | @param[in] plugin | |
950 | Plugin of which to get the number of contained filter | |
951 | component classes. | |
952 | ||
953 | @returns | |
954 | Number of contained filter component classes in \bt_p{plugin}. | |
955 | ||
956 | @bt_pre_not_null{plugin} | |
957 | */ | |
958 | extern uint64_t bt_plugin_get_filter_component_class_count( | |
959 | const bt_plugin *plugin); | |
960 | ||
961 | /*! | |
962 | @brief | |
963 | Returns the number of sink component classes contained in the | |
964 | plugin \bt_p{plugin}. | |
965 | ||
966 | @param[in] plugin | |
967 | Plugin of which to get the number of contained sink | |
968 | component classes. | |
969 | ||
970 | @returns | |
971 | Number of contained sink component classes in \bt_p{plugin}. | |
972 | ||
973 | @bt_pre_not_null{plugin} | |
974 | */ | |
975 | extern uint64_t bt_plugin_get_sink_component_class_count( | |
976 | const bt_plugin *plugin); | |
977 | ||
978 | /*! | |
979 | @brief | |
980 | Borrows the source component class at index \bt_p{index} from the | |
981 | plugin \bt_p{plugin}. | |
982 | ||
983 | @param[in] plugin | |
984 | Plugin from which to borrow the source component class at index | |
985 | \bt_p{index}. | |
986 | @param[in] index | |
987 | Index of the source component class to borrow from \bt_p{plugin}. | |
988 | ||
989 | @returns | |
990 | @parblock | |
991 | \em Borrowed reference of the source component class of | |
992 | \bt_p{plugin} at index \bt_p{index}. | |
993 | ||
994 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
995 | @endparblock | |
996 | ||
997 | @bt_pre_not_null{plugin} | |
998 | @pre | |
999 | \bt_p{index} is less than the number of source component classes in | |
1000 | \bt_p{plugin} (as returned by | |
1001 | bt_plugin_get_source_component_class_count()). | |
1002 | ||
1003 | @sa bt_plugin_borrow_source_component_class_by_name_const() — | |
1004 | Borrows a source component class by name from a plugin. | |
1005 | */ | |
1006 | extern const bt_component_class_source * | |
1007 | bt_plugin_borrow_source_component_class_by_index_const( | |
1008 | const bt_plugin *plugin, uint64_t index); | |
1009 | ||
1010 | /*! | |
1011 | @brief | |
1012 | Borrows the filter component class at index \bt_p{index} from the | |
1013 | plugin \bt_p{plugin}. | |
1014 | ||
1015 | @param[in] plugin | |
1016 | Plugin from which to borrow the filter component class at index | |
1017 | \bt_p{index}. | |
1018 | @param[in] index | |
1019 | Index of the filter component class to borrow from \bt_p{plugin}. | |
1020 | ||
1021 | @returns | |
1022 | @parblock | |
1023 | \em Borrowed reference of the filter component class of | |
1024 | \bt_p{plugin} at index \bt_p{index}. | |
1025 | ||
1026 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
1027 | @endparblock | |
1028 | ||
1029 | @bt_pre_not_null{plugin} | |
1030 | @pre | |
1031 | \bt_p{index} is less than the number of filter component classes in | |
1032 | \bt_p{plugin} (as returned by | |
1033 | bt_plugin_get_source_component_class_count()). | |
1034 | ||
1035 | @sa bt_plugin_borrow_source_component_class_by_name_const() — | |
1036 | Borrows a filter component class by name from a plugin. | |
1037 | */ | |
1038 | extern const bt_component_class_filter * | |
1039 | bt_plugin_borrow_filter_component_class_by_index_const( | |
1040 | const bt_plugin *plugin, uint64_t index); | |
1041 | ||
1042 | /*! | |
1043 | @brief | |
1044 | Borrows the sink component class at index \bt_p{index} from the | |
1045 | plugin \bt_p{plugin}. | |
1046 | ||
1047 | @param[in] plugin | |
1048 | Plugin from which to borrow the sink component class at index | |
1049 | \bt_p{index}. | |
1050 | @param[in] index | |
1051 | Index of the sink component class to borrow from \bt_p{plugin}. | |
1052 | ||
1053 | @returns | |
1054 | @parblock | |
1055 | \em Borrowed reference of the sink component class of | |
1056 | \bt_p{plugin} at index \bt_p{index}. | |
1057 | ||
1058 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
1059 | @endparblock | |
1060 | ||
1061 | @bt_pre_not_null{plugin} | |
1062 | @pre | |
1063 | \bt_p{index} is less than the number of sink component classes in | |
1064 | \bt_p{plugin} (as returned by | |
1065 | bt_plugin_get_source_component_class_count()). | |
1066 | ||
1067 | @sa bt_plugin_borrow_source_component_class_by_name_const() — | |
1068 | Borrows a sink component class by name from a plugin. | |
1069 | */ | |
1070 | extern const bt_component_class_sink * | |
1071 | bt_plugin_borrow_sink_component_class_by_index_const( | |
1072 | const bt_plugin *plugin, uint64_t index); | |
1073 | ||
1074 | /*! | |
1075 | @brief | |
1076 | Borrows the source component class named \bt_p{name} from the | |
1077 | plugin \bt_p{plugin}. | |
1078 | ||
1079 | If no source component class has the name \bt_p{name} within | |
1080 | \bt_p{plugin}, this function returns \c NULL. | |
1081 | ||
1082 | @param[in] plugin | |
1083 | Plugin from which to borrow the source component class named | |
1084 | \bt_p{name}. | |
1085 | @param[in] name | |
1086 | Name of the source component class to borrow from \bt_p{plugin}. | |
1087 | ||
1088 | @returns | |
1089 | @parblock | |
1090 | \em Borrowed reference of the source component class of | |
1091 | \bt_p{plugin} named \bt_p{name}, or \c NULL if no source component | |
1092 | class is named \bt_p{name} within \bt_p{plugin}. | |
1093 | ||
1094 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
1095 | @endparblock | |
1096 | ||
1097 | @bt_pre_not_null{plugin} | |
1098 | @bt_pre_not_null{name} | |
1099 | ||
1100 | @sa bt_plugin_borrow_source_component_class_by_index_const() — | |
1101 | Borrows a source component class by index from a plugin. | |
1102 | */ | |
1103 | extern const bt_component_class_source * | |
1104 | bt_plugin_borrow_source_component_class_by_name_const( | |
1105 | const bt_plugin *plugin, const char *name); | |
1106 | ||
1107 | /*! | |
1108 | @brief | |
1109 | Borrows the filter component class named \bt_p{name} from the | |
1110 | plugin \bt_p{plugin}. | |
1111 | ||
1112 | If no filter component class has the name \bt_p{name} within | |
1113 | \bt_p{plugin}, this function returns \c NULL. | |
1114 | ||
1115 | @param[in] plugin | |
1116 | Plugin from which to borrow the filter component class named | |
1117 | \bt_p{name}. | |
1118 | @param[in] name | |
1119 | Name of the filter component class to borrow from \bt_p{plugin}. | |
1120 | ||
1121 | @returns | |
1122 | @parblock | |
1123 | \em Borrowed reference of the filter component class of | |
1124 | \bt_p{plugin} named \bt_p{name}, or \c NULL if no filter component | |
1125 | class is named \bt_p{name} within \bt_p{plugin}. | |
1126 | ||
1127 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
1128 | @endparblock | |
1129 | ||
1130 | @bt_pre_not_null{plugin} | |
1131 | @bt_pre_not_null{name} | |
1132 | ||
1133 | @sa bt_plugin_borrow_filter_component_class_by_index_const() — | |
1134 | Borrows a filter component class by index from a plugin. | |
1135 | */ | |
1136 | extern const bt_component_class_filter * | |
1137 | bt_plugin_borrow_filter_component_class_by_name_const( | |
1138 | const bt_plugin *plugin, const char *name); | |
1139 | ||
1140 | /*! | |
1141 | @brief | |
1142 | Borrows the sink component class named \bt_p{name} from the | |
1143 | plugin \bt_p{plugin}. | |
1144 | ||
1145 | If no sink component class has the name \bt_p{name} within | |
1146 | \bt_p{plugin}, this function returns \c NULL. | |
1147 | ||
1148 | @param[in] plugin | |
1149 | Plugin from which to borrow the sink component class named | |
1150 | \bt_p{name}. | |
1151 | @param[in] name | |
1152 | Name of the sink component class to borrow from \bt_p{plugin}. | |
1153 | ||
1154 | @returns | |
1155 | @parblock | |
1156 | \em Borrowed reference of the sink component class of | |
1157 | \bt_p{plugin} named \bt_p{name}, or \c NULL if no sink component | |
1158 | class is named \bt_p{name} within \bt_p{plugin}. | |
1159 | ||
1160 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
1161 | @endparblock | |
1162 | ||
1163 | @bt_pre_not_null{plugin} | |
1164 | @bt_pre_not_null{name} | |
1165 | ||
1166 | @sa bt_plugin_borrow_sink_component_class_by_index_const() — | |
1167 | Borrows a sink component class by index from a plugin. | |
1168 | */ | |
1169 | extern const bt_component_class_sink * | |
1170 | bt_plugin_borrow_sink_component_class_by_name_const( | |
1171 | const bt_plugin *plugin, const char *name); | |
1172 | ||
1173 | /*! @} */ | |
1174 | ||
1175 | /*! | |
1176 | @name Plugin reference count | |
1177 | @{ | |
1178 | */ | |
1179 | ||
1180 | /*! | |
1181 | @brief | |
1182 | Increments the \ref api-fund-shared-object "reference count" of | |
1183 | the plugin \bt_p{plugin}. | |
1184 | ||
1185 | @param[in] plugin | |
1186 | @parblock | |
1187 | Plugin of which to increment the reference count. | |
1188 | ||
1189 | Can be \c NULL. | |
1190 | @endparblock | |
1191 | ||
1192 | @sa bt_plugin_put_ref() — | |
1193 | Decrements the reference count of a plugin. | |
1194 | */ | |
1195 | extern void bt_plugin_get_ref(const bt_plugin *plugin); | |
1196 | ||
1197 | /*! | |
1198 | @brief | |
1199 | Decrements the \ref api-fund-shared-object "reference count" of | |
1200 | the plugin \bt_p{plugin}. | |
1201 | ||
1202 | @param[in] plugin | |
1203 | @parblock | |
1204 | Plugin of which to decrement the reference count. | |
1205 | ||
1206 | Can be \c NULL. | |
1207 | @endparblock | |
1208 | ||
1209 | @sa bt_plugin_get_ref() — | |
1210 | Increments the reference count of a plugin. | |
1211 | */ | |
1212 | extern void bt_plugin_put_ref(const bt_plugin *plugin); | |
1213 | ||
1214 | /*! | |
1215 | @brief | |
1216 | Decrements the reference count of the plugin \bt_p{_plugin}, and | |
1217 | then sets \bt_p{_plugin} to \c NULL. | |
1218 | ||
1219 | @param _plugin | |
1220 | @parblock | |
1221 | Plugin of which to decrement the reference count. | |
1222 | ||
1223 | Can contain \c NULL. | |
1224 | @endparblock | |
1225 | ||
1226 | @bt_pre_assign_expr{_plugin} | |
1227 | */ | |
1228 | #define BT_PLUGIN_PUT_REF_AND_RESET(_plugin) \ | |
1229 | do { \ | |
1230 | bt_plugin_put_ref(_plugin); \ | |
1231 | (_plugin) = NULL; \ | |
1232 | } while (0) | |
1233 | ||
1234 | /*! | |
1235 | @brief | |
1236 | Decrements the reference count of the plugin \bt_p{_dst}, sets | |
1237 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
1238 | ||
1239 | This macro effectively moves a plugin reference from the expression | |
1240 | \bt_p{_src} to the expression \bt_p{_dst}, putting the existing | |
1241 | \bt_p{_dst} reference. | |
1242 | ||
1243 | @param _dst | |
1244 | @parblock | |
1245 | Destination expression. | |
1246 | ||
1247 | Can contain \c NULL. | |
1248 | @endparblock | |
1249 | @param _src | |
1250 | @parblock | |
1251 | Source expression. | |
1252 | ||
1253 | Can contain \c NULL. | |
1254 | @endparblock | |
1255 | ||
1256 | @bt_pre_assign_expr{_dst} | |
1257 | @bt_pre_assign_expr{_src} | |
1258 | */ | |
1259 | #define BT_PLUGIN_MOVE_REF(_dst, _src) \ | |
1260 | do { \ | |
1261 | bt_plugin_put_ref(_dst); \ | |
1262 | (_dst) = (_src); \ | |
1263 | (_src) = NULL; \ | |
1264 | } while (0) | |
1265 | ||
1266 | /*! @} */ | |
1267 | ||
1268 | /*! | |
1269 | @name Plugin set plugin access | |
1270 | @{ | |
1271 | */ | |
1272 | ||
1273 | /*! | |
1274 | @brief | |
1275 | Returns the number of plugins contained in the | |
1276 | plugin set \bt_p{plugin_set}. | |
1277 | ||
1278 | @param[in] plugin_set | |
1279 | Plugin set of which to get the number of contained plugins. | |
1280 | ||
1281 | @returns | |
1282 | Number of contained plugins in \bt_p{plugin_set}. | |
1283 | ||
1284 | @bt_pre_not_null{plugin} | |
1285 | */ | |
1286 | extern uint64_t bt_plugin_set_get_plugin_count( | |
1287 | const bt_plugin_set *plugin_set); | |
1288 | ||
1289 | /*! | |
1290 | @brief | |
1291 | Borrows the plugin at index \bt_p{index} from the plugin set | |
1292 | \bt_p{plugin_set}. | |
1293 | ||
1294 | @param[in] plugin_set | |
1295 | Plugin set from which to borrow the plugin at index \bt_p{index}. | |
1296 | @param[in] index | |
1297 | Index of the plugin to borrow from \bt_p{plugin_set}. | |
1298 | ||
1299 | @returns | |
1300 | @parblock | |
1301 | \em Borrowed reference of the plugin of \bt_p{plugin_set} at index | |
1302 | \bt_p{index}. | |
1303 | ||
1304 | The returned pointer remains valid until \bt_p{plugin_set} is | |
1305 | modified. | |
1306 | @endparblock | |
1307 | ||
1308 | @bt_pre_not_null{plugin_set} | |
1309 | @pre | |
1310 | \bt_p{index} is less than the number of plugins in | |
1311 | \bt_p{plugin_set} (as returned by bt_plugin_set_get_plugin_count()). | |
1312 | */ | |
1313 | extern const bt_plugin *bt_plugin_set_borrow_plugin_by_index_const( | |
1314 | const bt_plugin_set *plugin_set, uint64_t index); | |
1315 | ||
1316 | /*! @} */ | |
1317 | ||
1318 | /*! | |
1319 | @name Plugin set reference count | |
1320 | @{ | |
1321 | */ | |
1322 | ||
1323 | /*! | |
1324 | @brief | |
1325 | Increments the \ref api-fund-shared-object "reference count" of | |
1326 | the plugin set \bt_p{plugin_set}. | |
1327 | ||
1328 | @param[in] plugin_set | |
1329 | @parblock | |
1330 | Plugin set of which to increment the reference count. | |
1331 | ||
1332 | Can be \c NULL. | |
1333 | @endparblock | |
1334 | ||
1335 | @sa bt_plugin_set_put_ref() — | |
1336 | Decrements the reference count of a plugin set. | |
1337 | */ | |
1338 | extern void bt_plugin_set_get_ref(const bt_plugin_set *plugin_set); | |
1339 | ||
1340 | /*! | |
1341 | @brief | |
1342 | Decrements the \ref api-fund-shared-object "reference count" of | |
1343 | the plugin set \bt_p{plugin_set}. | |
1344 | ||
1345 | @param[in] plugin_set | |
1346 | @parblock | |
1347 | Plugin set of which to decrement the reference count. | |
1348 | ||
1349 | Can be \c NULL. | |
1350 | @endparblock | |
1351 | ||
1352 | @sa bt_plugin_set_get_ref() — | |
1353 | Increments the reference count of a plugin set. | |
1354 | */ | |
1355 | extern void bt_plugin_set_put_ref(const bt_plugin_set *plugin_set); | |
1356 | ||
1357 | /*! | |
1358 | @brief | |
1359 | Decrements the reference count of the plugin set \bt_p{_plugin_set}, | |
1360 | and then sets \bt_p{_plugin_set} to \c NULL. | |
1361 | ||
1362 | @param _plugin_set | |
1363 | @parblock | |
1364 | Plugin set of which to decrement the reference count. | |
1365 | ||
1366 | Can contain \c NULL. | |
1367 | @endparblock | |
1368 | ||
1369 | @bt_pre_assign_expr{_plugin_set} | |
1370 | */ | |
1371 | #define BT_PLUGIN_SET_PUT_REF_AND_RESET(_plugin_set) \ | |
1372 | do { \ | |
1373 | bt_plugin_set_put_ref(_plugin_set); \ | |
1374 | (_plugin_set) = NULL; \ | |
1375 | } while (0) | |
1376 | ||
1377 | /*! | |
1378 | @brief | |
1379 | Decrements the reference count of the plugin set \bt_p{_dst}, sets | |
1380 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
1381 | ||
1382 | This macro effectively moves a plugin set reference from the expression | |
1383 | \bt_p{_src} to the expression \bt_p{_dst}, putting the existing | |
1384 | \bt_p{_dst} reference. | |
1385 | ||
1386 | @param _dst | |
1387 | @parblock | |
1388 | Destination expression. | |
1389 | ||
1390 | Can contain \c NULL. | |
1391 | @endparblock | |
1392 | @param _src | |
1393 | @parblock | |
1394 | Source expression. | |
1395 | ||
1396 | Can contain \c NULL. | |
1397 | @endparblock | |
1398 | ||
1399 | @bt_pre_assign_expr{_dst} | |
1400 | @bt_pre_assign_expr{_src} | |
1401 | */ | |
1402 | #define BT_PLUGIN_SET_MOVE_REF(_dst, _src) \ | |
1403 | do { \ | |
1404 | bt_plugin_set_put_ref(_dst); \ | |
1405 | (_dst) = (_src); \ | |
1406 | (_src) = NULL; \ | |
1407 | } while (0) | |
1408 | ||
1409 | /*! @} */ | |
1410 | ||
1411 | /*! @} */ | |
1412 | ||
1413 | #ifdef __cplusplus | |
1414 | } | |
1415 | #endif | |
1416 | ||
1417 | #endif /* BABELTRACE2_PLUGIN_PLUGIN_LOADING_H */ |