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