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, | |
4c81a2b7 PP |
380 | bt_bool fail_on_load_error, const bt_plugin **plugin) |
381 | __BT_NOEXCEPT; | |
43c59509 PP |
382 | |
383 | /*! | |
384 | @brief | |
385 | Status codes for bt_plugin_find_all(). | |
386 | */ | |
387 | typedef enum bt_plugin_find_all_status { | |
388 | /*! | |
389 | @brief | |
390 | Success. | |
391 | */ | |
392 | BT_PLUGIN_FIND_ALL_STATUS_OK = __BT_FUNC_STATUS_OK, | |
393 | ||
394 | /*! | |
395 | @brief | |
396 | No plugins found. | |
397 | */ | |
398 | BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND, | |
399 | ||
400 | /*! | |
401 | @brief | |
402 | Out of memory. | |
403 | */ | |
404 | BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
405 | ||
406 | /*! | |
407 | @brief | |
408 | Error. | |
409 | */ | |
410 | BT_PLUGIN_FIND_ALL_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
411 | } bt_plugin_find_all_status; | |
412 | ||
413 | /*! | |
414 | @brief | |
415 | Finds and loads all the plugins from the default | |
416 | plugin search directories and static plugins, setting | |
417 | \bt_p{*plugins} to the result. | |
418 | ||
419 | This function returns all the plugins within, in order: | |
420 | ||
421 | -# <strong>If the \bt_p{find_in_std_env_var} parameter is | |
422 | #BT_TRUE</strong>, | |
423 | the colon-separated (or semicolon-separated on Windows) list of | |
424 | directories in the \c BABELTRACE_PLUGIN_PATH environment variable, | |
425 | if it's set. | |
426 | ||
427 | The function searches each directory in this list, without recursing. | |
428 | ||
429 | -# <strong>If the \bt_p{find_in_user_dir} parameter is | |
430 | #BT_TRUE</strong>, <code>$HOME/.local/lib/babeltrace2/plugins</code>, | |
431 | without recursing. | |
432 | ||
433 | -# <strong>If the \bt_p{find_in_sys_dir} is #BT_TRUE</strong>, the | |
434 | system \bt_name plugin directory, typically | |
435 | <code>/usr/lib/babeltrace2/plugins</code> or | |
436 | <code>/usr/local/lib/babeltrace2/plugins</code> on Linux, without | |
437 | recursing. | |
438 | ||
439 | -# <strong>If the \bt_p{find_in_static} is #BT_TRUE</strong>, | |
440 | the static plugins. | |
441 | ||
442 | During the search process, if a found plugin shares the name of an | |
443 | already loaded plugin, this function ignores it and continues. | |
444 | ||
445 | If this function finds a file which looks like a plugin (shared object | |
446 | file or Python file with the \c bt_plugin_ prefix), but it fails to load | |
447 | it for any reason, the function: | |
448 | ||
449 | <dl> | |
450 | <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt> | |
451 | <dd>Returns #BT_PLUGIN_FIND_ALL_STATUS_ERROR.</dd> | |
452 | ||
453 | <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt> | |
454 | <dd>Ignores the loading error and continues searching.</dd> | |
455 | </dl> | |
456 | ||
457 | If this function doesn't find any plugin, it returns | |
458 | #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND and does \em not set | |
459 | \bt_p{*plugins}. | |
460 | ||
461 | @param[in] find_in_std_env_var | |
462 | #BT_TRUE to try to find all the plugins in the | |
463 | colon-separated (or semicolon-separated on Windows) list of | |
464 | directories in the \c BABELTRACE_PLUGIN_PATH environment variable. | |
465 | @param[in] find_in_user_dir | |
466 | #BT_TRUE to try to find all the plugins in | |
467 | the <code>$HOME/.local/lib/babeltrace2/plugins</code> directory, | |
468 | without recursing. | |
469 | @param[in] find_in_sys_dir | |
470 | #BT_TRUE to try to find all the plugins in the system \bt_name | |
471 | plugin directory. | |
472 | @param[in] find_in_static | |
473 | #BT_TRUE to try to find all the plugins in the static plugins. | |
474 | @param[in] fail_on_load_error | |
475 | #BT_TRUE to make this function return | |
476 | #BT_PLUGIN_FIND_ALL_STATUS_ERROR on any plugin loading error instead | |
477 | of ignoring it. | |
478 | @param[out] plugins | |
479 | <strong>On success</strong>, \bt_p{*plugins} is a new plugin set | |
480 | reference which contains all the plugins found from the default | |
481 | plugin search directories and static plugins. | |
482 | ||
483 | @retval #BT_PLUGIN_FIND_ALL_STATUS_OK | |
484 | Success. | |
485 | @retval #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND | |
486 | No plugins found. | |
487 | @retval #BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR | |
488 | Out of memory. | |
489 | @retval #BT_PLUGIN_FIND_ALL_STATUS_ERROR | |
490 | Error. | |
491 | ||
492 | @pre | |
493 | At least one of the \bt_p{find_in_std_env_var}, | |
494 | \bt_p{find_in_user_dir}, \bt_p{find_in_sys_dir}, and | |
495 | \bt_p{find_in_static} parameters is #BT_TRUE. | |
496 | @bt_pre_not_null{plugins} | |
497 | ||
498 | @sa bt_plugin_find() — | |
499 | Finds and loads a single plugin by name from the default plugin search | |
500 | directories and static plugins. | |
501 | */ | |
502 | bt_plugin_find_all_status bt_plugin_find_all(bt_bool find_in_std_env_var, | |
503 | bt_bool find_in_user_dir, bt_bool find_in_sys_dir, | |
504 | bt_bool find_in_static, bt_bool fail_on_load_error, | |
4c81a2b7 | 505 | const bt_plugin_set **plugins) __BT_NOEXCEPT; |
43c59509 PP |
506 | |
507 | /*! | |
508 | @brief | |
509 | Status codes for bt_plugin_find_all_from_file(). | |
510 | */ | |
511 | typedef enum bt_plugin_find_all_from_file_status { | |
512 | /*! | |
513 | @brief | |
514 | Success. | |
515 | */ | |
516 | BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK = __BT_FUNC_STATUS_OK, | |
517 | ||
518 | /*! | |
519 | @brief | |
520 | No plugins found. | |
521 | */ | |
522 | BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND, | |
523 | ||
524 | /*! | |
525 | @brief | |
526 | Out of memory. | |
527 | */ | |
528 | BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
529 | ||
530 | /*! | |
531 | @brief | |
532 | Error. | |
533 | */ | |
534 | BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
535 | } bt_plugin_find_all_from_file_status; | |
536 | ||
537 | /*! | |
538 | @brief | |
539 | Finds and loads all the plugins from the file with path \bt_p{path}, | |
540 | setting \bt_p{*plugins} to the result. | |
541 | ||
542 | @note | |
543 | A plugin's name is not related to the name of its file (shared | |
544 | object or Python file). For example, a plugin found in the file | |
545 | \c patente.so can be named <code>Dan</code>. | |
546 | ||
547 | If any plugin loading error occurs during this function's execution, the | |
548 | function: | |
549 | ||
550 | <dl> | |
551 | <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt> | |
552 | <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR.</dd> | |
553 | ||
554 | <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt> | |
555 | <dd>Ignores the loading error and continues.</dd> | |
556 | </dl> | |
557 | ||
558 | If this function doesn't find any plugin, it returns | |
559 | #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND and does \em not set | |
560 | \bt_p{*plugins}. | |
561 | ||
562 | @param[in] path | |
563 | Path of the file in which to find and load all the plugins. | |
564 | @param[in] fail_on_load_error | |
565 | #BT_TRUE to make this function return | |
566 | #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR on any plugin loading | |
567 | error instead of ignoring it. | |
568 | @param[out] plugins | |
569 | <strong>On success</strong>, \bt_p{*plugins} is a new plugin set | |
570 | reference which contains all the plugins found in the file with path | |
571 | \bt_p{path}. | |
572 | ||
573 | @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK | |
574 | Success. | |
575 | @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND | |
576 | No plugins found. | |
577 | @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR | |
578 | Out of memory. | |
579 | @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR | |
580 | Error. | |
581 | ||
582 | @bt_pre_not_null{path} | |
583 | @pre | |
584 | \bt_p{path} is the path of a regular file. | |
585 | @bt_pre_not_null{plugins} | |
586 | ||
587 | @sa bt_plugin_find_all_from_dir() — | |
588 | Finds and loads all plugins from a given directory. | |
589 | */ | |
590 | extern bt_plugin_find_all_from_file_status bt_plugin_find_all_from_file( | |
591 | const char *path, bt_bool fail_on_load_error, | |
4c81a2b7 | 592 | const bt_plugin_set **plugins) __BT_NOEXCEPT; |
43c59509 PP |
593 | |
594 | /*! | |
595 | @brief | |
596 | Status codes for bt_plugin_find_all_from_dir(). | |
597 | */ | |
598 | typedef enum bt_plugin_find_all_from_dir_status { | |
599 | /*! | |
600 | @brief | |
601 | Success. | |
602 | */ | |
603 | BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK = __BT_FUNC_STATUS_OK, | |
604 | ||
605 | /*! | |
606 | @brief | |
607 | No plugins found. | |
608 | */ | |
609 | BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND, | |
610 | ||
611 | /*! | |
612 | @brief | |
613 | Out of memory. | |
614 | */ | |
615 | BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
616 | ||
617 | /*! | |
618 | @brief | |
619 | Error. | |
620 | */ | |
621 | BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
622 | } bt_plugin_find_all_from_dir_status; | |
623 | ||
624 | /*! | |
625 | @brief | |
626 | Finds and loads all the plugins from the directory with path | |
627 | \bt_p{path}, setting \bt_p{*plugins} to the result. | |
628 | ||
629 | If \bt_p{recurse} is #BT_TRUE, this function recurses into the | |
630 | subdirectories of \bt_p{path} to find plugins. | |
631 | ||
632 | During the search process, if a found plugin shares the name of an | |
633 | already loaded plugin, this function ignores it and continues. | |
634 | ||
635 | @attention | |
636 | As of \bt_name_version_min_maj, the file and directory traversal | |
637 | order is undefined. | |
638 | ||
639 | If any plugin loading error occurs during this function's execution, the | |
640 | function: | |
641 | ||
642 | <dl> | |
643 | <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt> | |
644 | <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR.</dd> | |
645 | ||
646 | <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt> | |
647 | <dd>Ignores the loading error and continues.</dd> | |
648 | </dl> | |
649 | ||
650 | If this function doesn't find any plugin, it returns | |
651 | #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND and does \em not set | |
652 | \bt_p{*plugins}. | |
653 | ||
654 | @param[in] path | |
655 | Path of the directory in which to find and load all the plugins. | |
656 | @param[in] recurse | |
657 | #BT_TRUE to make this function recurse into the subdirectories | |
658 | of \bt_p{path}. | |
659 | @param[in] fail_on_load_error | |
660 | #BT_TRUE to make this function return | |
661 | #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR on any plugin loading | |
662 | error instead of ignoring it. | |
663 | @param[out] plugins | |
664 | <strong>On success</strong>, \bt_p{*plugins} is a new plugin set | |
665 | reference which contains all the plugins found in the directory with | |
666 | path \bt_p{path}. | |
667 | ||
668 | @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK | |
669 | Success. | |
670 | @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND | |
671 | No plugins found. | |
672 | @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR | |
673 | Out of memory. | |
674 | @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR | |
675 | Error. | |
676 | ||
677 | @bt_pre_not_null{path} | |
678 | @pre | |
679 | \bt_p{path} is the path of a directory. | |
680 | @bt_pre_not_null{plugins} | |
681 | ||
682 | @sa bt_plugin_find_all_from_file() — | |
683 | Finds and loads all plugins from a given file. | |
684 | */ | |
685 | extern bt_plugin_find_all_from_dir_status bt_plugin_find_all_from_dir( | |
686 | const char *path, bt_bool recurse, bt_bool fail_on_load_error, | |
4c81a2b7 | 687 | const bt_plugin_set **plugins) __BT_NOEXCEPT; |
43c59509 PP |
688 | |
689 | /*! | |
690 | @brief | |
691 | Status codes for bt_plugin_find_all_from_static(). | |
692 | */ | |
693 | typedef enum bt_plugin_find_all_from_static_status { | |
694 | /*! | |
695 | @brief | |
696 | Success. | |
697 | */ | |
698 | BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK = __BT_FUNC_STATUS_OK, | |
699 | ||
700 | /*! | |
701 | @brief | |
702 | No static plugins found. | |
703 | */ | |
704 | BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND, | |
705 | ||
706 | /*! | |
707 | @brief | |
708 | Out of memory. | |
709 | */ | |
710 | BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
711 | ||
712 | /*! | |
713 | @brief | |
714 | Error. | |
715 | */ | |
716 | BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
717 | } bt_plugin_find_all_from_static_status; | |
718 | ||
719 | /*! | |
720 | @brief | |
721 | Finds and loads all the static plugins, | |
722 | setting \bt_p{*plugins} to the result. | |
723 | ||
724 | A static plugin is built directly into the application or library | |
725 | instead of being a separate shared object file. | |
726 | ||
727 | If any plugin loading error occurs during this function's execution, the | |
728 | function: | |
729 | ||
730 | <dl> | |
731 | <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt> | |
732 | <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR.</dd> | |
733 | ||
734 | <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt> | |
735 | <dd>Ignores the loading error and continues.</dd> | |
736 | </dl> | |
737 | ||
738 | If this function doesn't find any plugin, it returns | |
739 | #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND and does \em not set | |
740 | \bt_p{*plugins}. | |
741 | ||
742 | @param[in] fail_on_load_error | |
743 | #BT_TRUE to make this function return | |
744 | #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR on any plugin loading | |
745 | error instead of ignoring it. | |
746 | @param[out] plugins | |
747 | <strong>On success</strong>, \bt_p{*plugins} is a new plugin set | |
748 | reference which contains all the static plugins. | |
749 | ||
750 | @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK | |
751 | Success. | |
752 | @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND | |
753 | No static plugins found. | |
754 | @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR | |
755 | Out of memory. | |
756 | @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR | |
757 | Error. | |
758 | ||
759 | @bt_pre_not_null{path} | |
760 | @bt_pre_not_null{plugins} | |
761 | */ | |
762 | extern bt_plugin_find_all_from_static_status bt_plugin_find_all_from_static( | |
4c81a2b7 PP |
763 | bt_bool fail_on_load_error, const bt_plugin_set **plugins) |
764 | __BT_NOEXCEPT; | |
43c59509 PP |
765 | |
766 | /*! @} */ | |
767 | ||
768 | /*! | |
769 | @name Plugin properties | |
770 | @{ | |
771 | */ | |
772 | ||
773 | /*! | |
774 | @brief | |
775 | Returns the name of the plugin \bt_p{plugin}. | |
776 | ||
777 | See the \ref api-plugin-prop-name "name" property. | |
778 | ||
779 | @param[in] plugin | |
780 | Plugin of which to get the name. | |
781 | ||
782 | @returns | |
783 | @parblock | |
784 | Name of \bt_p{plugin}. | |
785 | ||
786 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
787 | @endparblock | |
788 | ||
789 | @bt_pre_not_null{plugin} | |
790 | */ | |
4c81a2b7 | 791 | extern const char *bt_plugin_get_name(const bt_plugin *plugin) __BT_NOEXCEPT; |
43c59509 PP |
792 | |
793 | /*! | |
794 | @brief | |
795 | Returns the description of the plugin \bt_p{plugin}. | |
796 | ||
797 | See the \ref api-plugin-prop-descr "description" property. | |
798 | ||
799 | @param[in] plugin | |
800 | Plugin of which to get description. | |
801 | ||
802 | @returns | |
803 | @parblock | |
804 | Description of \bt_p{plugin}, or \c NULL if not available. | |
805 | ||
806 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
807 | @endparblock | |
808 | ||
809 | @bt_pre_not_null{plugin} | |
810 | */ | |
4c81a2b7 PP |
811 | extern const char *bt_plugin_get_description(const bt_plugin *plugin) |
812 | __BT_NOEXCEPT; | |
43c59509 PP |
813 | |
814 | /*! | |
815 | @brief | |
816 | Returns the name(s) of the author(s) of the plugin \bt_p{plugin}. | |
817 | ||
818 | See the \ref api-plugin-prop-author "author name(s)" property. | |
819 | ||
820 | @param[in] plugin | |
821 | Plugin of which to get the author name(s). | |
822 | ||
823 | @returns | |
824 | @parblock | |
825 | Author name(s) of \bt_p{plugin}, or \c NULL if not available. | |
826 | ||
827 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
828 | @endparblock | |
829 | ||
830 | @bt_pre_not_null{plugin} | |
831 | */ | |
4c81a2b7 | 832 | extern const char *bt_plugin_get_author(const bt_plugin *plugin) __BT_NOEXCEPT; |
43c59509 PP |
833 | |
834 | /*! | |
835 | @brief | |
836 | Returns the license text or the license name of the plugin | |
837 | \bt_p{plugin}. | |
838 | ||
839 | See the \ref api-plugin-prop-license "license" property. | |
840 | ||
841 | @param[in] plugin | |
842 | Plugin of which to get the license. | |
843 | ||
844 | @returns | |
845 | @parblock | |
846 | License of \bt_p{plugin}, or \c NULL if not available. | |
847 | ||
848 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
849 | @endparblock | |
850 | ||
851 | @bt_pre_not_null{plugin} | |
852 | */ | |
4c81a2b7 | 853 | extern const char *bt_plugin_get_license(const bt_plugin *plugin) __BT_NOEXCEPT; |
43c59509 PP |
854 | |
855 | /*! | |
856 | @brief | |
857 | Returns the path of the file which contains the plugin | |
858 | \bt_p{plugin}. | |
859 | ||
860 | See the \ref api-plugin-prop-path "path" property. | |
861 | ||
862 | This function returns \c NULL if \bt_p{plugin} is a static plugin | |
863 | because a static plugin has no path property. | |
864 | ||
865 | @param[in] plugin | |
866 | Plugin of which to get the containing file's path. | |
867 | ||
868 | @returns | |
869 | @parblock | |
870 | Path of the file which contains \bt_p{plugin}, or \c NULL if | |
871 | not available. | |
872 | ||
873 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
874 | @endparblock | |
875 | ||
876 | @bt_pre_not_null{plugin} | |
877 | */ | |
4c81a2b7 | 878 | extern const char *bt_plugin_get_path(const bt_plugin *plugin) __BT_NOEXCEPT; |
43c59509 PP |
879 | |
880 | /*! | |
881 | @brief | |
882 | Returns the version of the plugin \bt_p{plugin}. | |
883 | ||
884 | See the \ref api-plugin-prop-version "version" property. | |
885 | ||
886 | @param[in] plugin | |
887 | Plugin of which to get the version. | |
888 | @param[out] major | |
889 | <strong>If not \c NULL and this function returns | |
890 | #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*major} is the | |
891 | major version of \bt_p{plugin}. | |
892 | @param[out] minor | |
893 | <strong>If not \c NULL and this function returns | |
894 | #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*minor} is the | |
895 | minor version of \bt_p{plugin}. | |
896 | @param[out] patch | |
897 | <strong>If not \c NULL and this function returns | |
898 | #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*patch} is the | |
899 | patch version of \bt_p{plugin}. | |
900 | @param[out] extra | |
901 | @parblock | |
902 | <strong>If not \c NULL and this function returns | |
903 | #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*extra} is the | |
904 | version's extra information of \bt_p{plugin}. | |
905 | ||
906 | \bt_p{*extra} can be \c NULL if the plugin's version has no extra | |
907 | information. | |
908 | ||
909 | \bt_p{*extra} remains valid as long as \bt_p{plugin} exists. | |
910 | @endparblock | |
911 | ||
912 | @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE | |
913 | The version of \bt_p{plugin} is available. | |
914 | @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE | |
915 | The version of \bt_p{plugin} is not available. | |
916 | ||
917 | @bt_pre_not_null{plugin} | |
918 | */ | |
919 | extern bt_property_availability bt_plugin_get_version( | |
920 | const bt_plugin *plugin, unsigned int *major, | |
4c81a2b7 PP |
921 | unsigned int *minor, unsigned int *patch, const char **extra) |
922 | __BT_NOEXCEPT; | |
43c59509 PP |
923 | |
924 | /*! @} */ | |
925 | ||
926 | /*! | |
927 | @name Plugin component class access | |
928 | @{ | |
929 | */ | |
930 | ||
931 | /*! | |
932 | @brief | |
933 | Returns the number of source component classes contained in the | |
934 | plugin \bt_p{plugin}. | |
935 | ||
936 | @param[in] plugin | |
937 | Plugin of which to get the number of contained source | |
938 | component classes. | |
939 | ||
940 | @returns | |
941 | Number of contained source component classes in \bt_p{plugin}. | |
942 | ||
943 | @bt_pre_not_null{plugin} | |
944 | */ | |
945 | extern uint64_t bt_plugin_get_source_component_class_count( | |
4c81a2b7 | 946 | const bt_plugin *plugin) __BT_NOEXCEPT; |
43c59509 PP |
947 | |
948 | /*! | |
949 | @brief | |
950 | Returns the number of filter component classes contained in the | |
951 | plugin \bt_p{plugin}. | |
952 | ||
953 | @param[in] plugin | |
954 | Plugin of which to get the number of contained filter | |
955 | component classes. | |
956 | ||
957 | @returns | |
958 | Number of contained filter component classes in \bt_p{plugin}. | |
959 | ||
960 | @bt_pre_not_null{plugin} | |
961 | */ | |
962 | extern uint64_t bt_plugin_get_filter_component_class_count( | |
4c81a2b7 | 963 | const bt_plugin *plugin) __BT_NOEXCEPT; |
43c59509 PP |
964 | |
965 | /*! | |
966 | @brief | |
967 | Returns the number of sink component classes contained in the | |
968 | plugin \bt_p{plugin}. | |
969 | ||
970 | @param[in] plugin | |
971 | Plugin of which to get the number of contained sink | |
972 | component classes. | |
973 | ||
974 | @returns | |
975 | Number of contained sink component classes in \bt_p{plugin}. | |
976 | ||
977 | @bt_pre_not_null{plugin} | |
978 | */ | |
979 | extern uint64_t bt_plugin_get_sink_component_class_count( | |
4c81a2b7 | 980 | const bt_plugin *plugin) __BT_NOEXCEPT; |
43c59509 PP |
981 | |
982 | /*! | |
983 | @brief | |
984 | Borrows the source component class at index \bt_p{index} from the | |
985 | plugin \bt_p{plugin}. | |
986 | ||
987 | @param[in] plugin | |
988 | Plugin from which to borrow the source component class at index | |
989 | \bt_p{index}. | |
990 | @param[in] index | |
991 | Index of the source component class to borrow from \bt_p{plugin}. | |
992 | ||
993 | @returns | |
994 | @parblock | |
995 | \em Borrowed reference of the source component class of | |
996 | \bt_p{plugin} at index \bt_p{index}. | |
997 | ||
998 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
999 | @endparblock | |
1000 | ||
1001 | @bt_pre_not_null{plugin} | |
1002 | @pre | |
1003 | \bt_p{index} is less than the number of source component classes in | |
1004 | \bt_p{plugin} (as returned by | |
1005 | bt_plugin_get_source_component_class_count()). | |
1006 | ||
1007 | @sa bt_plugin_borrow_source_component_class_by_name_const() — | |
1008 | Borrows a source component class by name from a plugin. | |
1009 | */ | |
1010 | extern const bt_component_class_source * | |
1011 | bt_plugin_borrow_source_component_class_by_index_const( | |
4c81a2b7 | 1012 | const bt_plugin *plugin, uint64_t index) __BT_NOEXCEPT; |
43c59509 PP |
1013 | |
1014 | /*! | |
1015 | @brief | |
1016 | Borrows the filter component class at index \bt_p{index} from the | |
1017 | plugin \bt_p{plugin}. | |
1018 | ||
1019 | @param[in] plugin | |
1020 | Plugin from which to borrow the filter component class at index | |
1021 | \bt_p{index}. | |
1022 | @param[in] index | |
1023 | Index of the filter component class to borrow from \bt_p{plugin}. | |
1024 | ||
1025 | @returns | |
1026 | @parblock | |
1027 | \em Borrowed reference of the filter component class of | |
1028 | \bt_p{plugin} at index \bt_p{index}. | |
1029 | ||
1030 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
1031 | @endparblock | |
1032 | ||
1033 | @bt_pre_not_null{plugin} | |
1034 | @pre | |
1035 | \bt_p{index} is less than the number of filter component classes in | |
1036 | \bt_p{plugin} (as returned by | |
1037 | bt_plugin_get_source_component_class_count()). | |
1038 | ||
1039 | @sa bt_plugin_borrow_source_component_class_by_name_const() — | |
1040 | Borrows a filter component class by name from a plugin. | |
1041 | */ | |
1042 | extern const bt_component_class_filter * | |
1043 | bt_plugin_borrow_filter_component_class_by_index_const( | |
4c81a2b7 | 1044 | const bt_plugin *plugin, uint64_t index) __BT_NOEXCEPT; |
43c59509 PP |
1045 | |
1046 | /*! | |
1047 | @brief | |
1048 | Borrows the sink component class at index \bt_p{index} from the | |
1049 | plugin \bt_p{plugin}. | |
1050 | ||
1051 | @param[in] plugin | |
1052 | Plugin from which to borrow the sink component class at index | |
1053 | \bt_p{index}. | |
1054 | @param[in] index | |
1055 | Index of the sink component class to borrow from \bt_p{plugin}. | |
1056 | ||
1057 | @returns | |
1058 | @parblock | |
1059 | \em Borrowed reference of the sink component class of | |
1060 | \bt_p{plugin} at index \bt_p{index}. | |
1061 | ||
1062 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
1063 | @endparblock | |
1064 | ||
1065 | @bt_pre_not_null{plugin} | |
1066 | @pre | |
1067 | \bt_p{index} is less than the number of sink component classes in | |
1068 | \bt_p{plugin} (as returned by | |
1069 | bt_plugin_get_source_component_class_count()). | |
1070 | ||
1071 | @sa bt_plugin_borrow_source_component_class_by_name_const() — | |
1072 | Borrows a sink component class by name from a plugin. | |
1073 | */ | |
1074 | extern const bt_component_class_sink * | |
1075 | bt_plugin_borrow_sink_component_class_by_index_const( | |
4c81a2b7 | 1076 | const bt_plugin *plugin, uint64_t index) __BT_NOEXCEPT; |
43c59509 PP |
1077 | |
1078 | /*! | |
1079 | @brief | |
1080 | Borrows the source component class named \bt_p{name} from the | |
1081 | plugin \bt_p{plugin}. | |
1082 | ||
1083 | If no source component class has the name \bt_p{name} within | |
1084 | \bt_p{plugin}, this function returns \c NULL. | |
1085 | ||
1086 | @param[in] plugin | |
1087 | Plugin from which to borrow the source component class named | |
1088 | \bt_p{name}. | |
1089 | @param[in] name | |
1090 | Name of the source component class to borrow from \bt_p{plugin}. | |
1091 | ||
1092 | @returns | |
1093 | @parblock | |
1094 | \em Borrowed reference of the source component class of | |
1095 | \bt_p{plugin} named \bt_p{name}, or \c NULL if no source component | |
1096 | class is named \bt_p{name} within \bt_p{plugin}. | |
1097 | ||
1098 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
1099 | @endparblock | |
1100 | ||
1101 | @bt_pre_not_null{plugin} | |
1102 | @bt_pre_not_null{name} | |
1103 | ||
1104 | @sa bt_plugin_borrow_source_component_class_by_index_const() — | |
1105 | Borrows a source component class by index from a plugin. | |
1106 | */ | |
1107 | extern const bt_component_class_source * | |
1108 | bt_plugin_borrow_source_component_class_by_name_const( | |
4c81a2b7 | 1109 | const bt_plugin *plugin, const char *name) __BT_NOEXCEPT; |
43c59509 PP |
1110 | |
1111 | /*! | |
1112 | @brief | |
1113 | Borrows the filter component class named \bt_p{name} from the | |
1114 | plugin \bt_p{plugin}. | |
1115 | ||
1116 | If no filter component class has the name \bt_p{name} within | |
1117 | \bt_p{plugin}, this function returns \c NULL. | |
1118 | ||
1119 | @param[in] plugin | |
1120 | Plugin from which to borrow the filter component class named | |
1121 | \bt_p{name}. | |
1122 | @param[in] name | |
1123 | Name of the filter component class to borrow from \bt_p{plugin}. | |
1124 | ||
1125 | @returns | |
1126 | @parblock | |
1127 | \em Borrowed reference of the filter component class of | |
1128 | \bt_p{plugin} named \bt_p{name}, or \c NULL if no filter component | |
1129 | class is named \bt_p{name} within \bt_p{plugin}. | |
1130 | ||
1131 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
1132 | @endparblock | |
1133 | ||
1134 | @bt_pre_not_null{plugin} | |
1135 | @bt_pre_not_null{name} | |
1136 | ||
1137 | @sa bt_plugin_borrow_filter_component_class_by_index_const() — | |
1138 | Borrows a filter component class by index from a plugin. | |
1139 | */ | |
1140 | extern const bt_component_class_filter * | |
1141 | bt_plugin_borrow_filter_component_class_by_name_const( | |
4c81a2b7 | 1142 | const bt_plugin *plugin, const char *name) __BT_NOEXCEPT; |
43c59509 PP |
1143 | |
1144 | /*! | |
1145 | @brief | |
1146 | Borrows the sink component class named \bt_p{name} from the | |
1147 | plugin \bt_p{plugin}. | |
1148 | ||
1149 | If no sink component class has the name \bt_p{name} within | |
1150 | \bt_p{plugin}, this function returns \c NULL. | |
1151 | ||
1152 | @param[in] plugin | |
1153 | Plugin from which to borrow the sink component class named | |
1154 | \bt_p{name}. | |
1155 | @param[in] name | |
1156 | Name of the sink component class to borrow from \bt_p{plugin}. | |
1157 | ||
1158 | @returns | |
1159 | @parblock | |
1160 | \em Borrowed reference of the sink component class of | |
1161 | \bt_p{plugin} named \bt_p{name}, or \c NULL if no sink component | |
1162 | class is named \bt_p{name} within \bt_p{plugin}. | |
1163 | ||
1164 | The returned pointer remains valid as long as \bt_p{plugin} exists. | |
1165 | @endparblock | |
1166 | ||
1167 | @bt_pre_not_null{plugin} | |
1168 | @bt_pre_not_null{name} | |
1169 | ||
1170 | @sa bt_plugin_borrow_sink_component_class_by_index_const() — | |
1171 | Borrows a sink component class by index from a plugin. | |
1172 | */ | |
1173 | extern const bt_component_class_sink * | |
1174 | bt_plugin_borrow_sink_component_class_by_name_const( | |
4c81a2b7 | 1175 | const bt_plugin *plugin, const char *name) __BT_NOEXCEPT; |
43c59509 PP |
1176 | |
1177 | /*! @} */ | |
1178 | ||
1179 | /*! | |
1180 | @name Plugin reference count | |
1181 | @{ | |
1182 | */ | |
1183 | ||
1184 | /*! | |
1185 | @brief | |
1186 | Increments the \ref api-fund-shared-object "reference count" of | |
1187 | the plugin \bt_p{plugin}. | |
1188 | ||
1189 | @param[in] plugin | |
1190 | @parblock | |
1191 | Plugin of which to increment the reference count. | |
1192 | ||
1193 | Can be \c NULL. | |
1194 | @endparblock | |
1195 | ||
1196 | @sa bt_plugin_put_ref() — | |
1197 | Decrements the reference count of a plugin. | |
1198 | */ | |
4c81a2b7 | 1199 | extern void bt_plugin_get_ref(const bt_plugin *plugin) __BT_NOEXCEPT; |
43c59509 PP |
1200 | |
1201 | /*! | |
1202 | @brief | |
1203 | Decrements the \ref api-fund-shared-object "reference count" of | |
1204 | the plugin \bt_p{plugin}. | |
1205 | ||
1206 | @param[in] plugin | |
1207 | @parblock | |
1208 | Plugin of which to decrement the reference count. | |
1209 | ||
1210 | Can be \c NULL. | |
1211 | @endparblock | |
1212 | ||
1213 | @sa bt_plugin_get_ref() — | |
1214 | Increments the reference count of a plugin. | |
1215 | */ | |
4c81a2b7 | 1216 | extern void bt_plugin_put_ref(const bt_plugin *plugin) __BT_NOEXCEPT; |
43c59509 PP |
1217 | |
1218 | /*! | |
1219 | @brief | |
1220 | Decrements the reference count of the plugin \bt_p{_plugin}, and | |
1221 | then sets \bt_p{_plugin} to \c NULL. | |
1222 | ||
1223 | @param _plugin | |
1224 | @parblock | |
1225 | Plugin of which to decrement the reference count. | |
1226 | ||
1227 | Can contain \c NULL. | |
1228 | @endparblock | |
1229 | ||
1230 | @bt_pre_assign_expr{_plugin} | |
1231 | */ | |
1232 | #define BT_PLUGIN_PUT_REF_AND_RESET(_plugin) \ | |
1233 | do { \ | |
1234 | bt_plugin_put_ref(_plugin); \ | |
1235 | (_plugin) = NULL; \ | |
1236 | } while (0) | |
1237 | ||
1238 | /*! | |
1239 | @brief | |
1240 | Decrements the reference count of the plugin \bt_p{_dst}, sets | |
1241 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
1242 | ||
1243 | This macro effectively moves a plugin reference from the expression | |
1244 | \bt_p{_src} to the expression \bt_p{_dst}, putting the existing | |
1245 | \bt_p{_dst} reference. | |
1246 | ||
1247 | @param _dst | |
1248 | @parblock | |
1249 | Destination expression. | |
1250 | ||
1251 | Can contain \c NULL. | |
1252 | @endparblock | |
1253 | @param _src | |
1254 | @parblock | |
1255 | Source expression. | |
1256 | ||
1257 | Can contain \c NULL. | |
1258 | @endparblock | |
1259 | ||
1260 | @bt_pre_assign_expr{_dst} | |
1261 | @bt_pre_assign_expr{_src} | |
1262 | */ | |
1263 | #define BT_PLUGIN_MOVE_REF(_dst, _src) \ | |
1264 | do { \ | |
1265 | bt_plugin_put_ref(_dst); \ | |
1266 | (_dst) = (_src); \ | |
1267 | (_src) = NULL; \ | |
1268 | } while (0) | |
1269 | ||
1270 | /*! @} */ | |
1271 | ||
1272 | /*! | |
1273 | @name Plugin set plugin access | |
1274 | @{ | |
1275 | */ | |
1276 | ||
1277 | /*! | |
1278 | @brief | |
1279 | Returns the number of plugins contained in the | |
1280 | plugin set \bt_p{plugin_set}. | |
1281 | ||
1282 | @param[in] plugin_set | |
1283 | Plugin set of which to get the number of contained plugins. | |
1284 | ||
1285 | @returns | |
1286 | Number of contained plugins in \bt_p{plugin_set}. | |
1287 | ||
1288 | @bt_pre_not_null{plugin} | |
1289 | */ | |
1290 | extern uint64_t bt_plugin_set_get_plugin_count( | |
4c81a2b7 | 1291 | const bt_plugin_set *plugin_set) __BT_NOEXCEPT; |
43c59509 PP |
1292 | |
1293 | /*! | |
1294 | @brief | |
1295 | Borrows the plugin at index \bt_p{index} from the plugin set | |
1296 | \bt_p{plugin_set}. | |
1297 | ||
1298 | @param[in] plugin_set | |
1299 | Plugin set from which to borrow the plugin at index \bt_p{index}. | |
1300 | @param[in] index | |
1301 | Index of the plugin to borrow from \bt_p{plugin_set}. | |
1302 | ||
1303 | @returns | |
1304 | @parblock | |
1305 | \em Borrowed reference of the plugin of \bt_p{plugin_set} at index | |
1306 | \bt_p{index}. | |
1307 | ||
1308 | The returned pointer remains valid until \bt_p{plugin_set} is | |
1309 | modified. | |
1310 | @endparblock | |
1311 | ||
1312 | @bt_pre_not_null{plugin_set} | |
1313 | @pre | |
1314 | \bt_p{index} is less than the number of plugins in | |
1315 | \bt_p{plugin_set} (as returned by bt_plugin_set_get_plugin_count()). | |
1316 | */ | |
1317 | extern const bt_plugin *bt_plugin_set_borrow_plugin_by_index_const( | |
4c81a2b7 | 1318 | const bt_plugin_set *plugin_set, uint64_t index) __BT_NOEXCEPT; |
43c59509 PP |
1319 | |
1320 | /*! @} */ | |
1321 | ||
1322 | /*! | |
1323 | @name Plugin set reference count | |
1324 | @{ | |
1325 | */ | |
1326 | ||
1327 | /*! | |
1328 | @brief | |
1329 | Increments the \ref api-fund-shared-object "reference count" of | |
1330 | the plugin set \bt_p{plugin_set}. | |
1331 | ||
1332 | @param[in] plugin_set | |
1333 | @parblock | |
1334 | Plugin set of which to increment the reference count. | |
1335 | ||
1336 | Can be \c NULL. | |
1337 | @endparblock | |
1338 | ||
1339 | @sa bt_plugin_set_put_ref() — | |
1340 | Decrements the reference count of a plugin set. | |
1341 | */ | |
4c81a2b7 PP |
1342 | extern void bt_plugin_set_get_ref(const bt_plugin_set *plugin_set) |
1343 | __BT_NOEXCEPT; | |
43c59509 PP |
1344 | |
1345 | /*! | |
1346 | @brief | |
1347 | Decrements the \ref api-fund-shared-object "reference count" of | |
1348 | the plugin set \bt_p{plugin_set}. | |
1349 | ||
1350 | @param[in] plugin_set | |
1351 | @parblock | |
1352 | Plugin set of which to decrement the reference count. | |
1353 | ||
1354 | Can be \c NULL. | |
1355 | @endparblock | |
1356 | ||
1357 | @sa bt_plugin_set_get_ref() — | |
1358 | Increments the reference count of a plugin set. | |
1359 | */ | |
4c81a2b7 PP |
1360 | extern void bt_plugin_set_put_ref(const bt_plugin_set *plugin_set) |
1361 | __BT_NOEXCEPT; | |
43c59509 PP |
1362 | |
1363 | /*! | |
1364 | @brief | |
1365 | Decrements the reference count of the plugin set \bt_p{_plugin_set}, | |
1366 | and then sets \bt_p{_plugin_set} to \c NULL. | |
1367 | ||
1368 | @param _plugin_set | |
1369 | @parblock | |
1370 | Plugin set of which to decrement the reference count. | |
1371 | ||
1372 | Can contain \c NULL. | |
1373 | @endparblock | |
1374 | ||
1375 | @bt_pre_assign_expr{_plugin_set} | |
1376 | */ | |
1377 | #define BT_PLUGIN_SET_PUT_REF_AND_RESET(_plugin_set) \ | |
1378 | do { \ | |
1379 | bt_plugin_set_put_ref(_plugin_set); \ | |
1380 | (_plugin_set) = NULL; \ | |
1381 | } while (0) | |
1382 | ||
1383 | /*! | |
1384 | @brief | |
1385 | Decrements the reference count of the plugin set \bt_p{_dst}, sets | |
1386 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
1387 | ||
1388 | This macro effectively moves a plugin set reference from the expression | |
1389 | \bt_p{_src} to the expression \bt_p{_dst}, putting the existing | |
1390 | \bt_p{_dst} reference. | |
1391 | ||
1392 | @param _dst | |
1393 | @parblock | |
1394 | Destination expression. | |
1395 | ||
1396 | Can contain \c NULL. | |
1397 | @endparblock | |
1398 | @param _src | |
1399 | @parblock | |
1400 | Source expression. | |
1401 | ||
1402 | Can contain \c NULL. | |
1403 | @endparblock | |
1404 | ||
1405 | @bt_pre_assign_expr{_dst} | |
1406 | @bt_pre_assign_expr{_src} | |
1407 | */ | |
1408 | #define BT_PLUGIN_SET_MOVE_REF(_dst, _src) \ | |
1409 | do { \ | |
1410 | bt_plugin_set_put_ref(_dst); \ | |
1411 | (_dst) = (_src); \ | |
1412 | (_src) = NULL; \ | |
1413 | } while (0) | |
1414 | ||
1415 | /*! @} */ | |
1416 | ||
1417 | /*! @} */ | |
1418 | ||
1419 | #ifdef __cplusplus | |
1420 | } | |
1421 | #endif | |
1422 | ||
1423 | #endif /* BABELTRACE2_PLUGIN_PLUGIN_LOADING_H */ |