C-Pluff C API 0.2.0
cpluff.h
Go to the documentation of this file.
1/*-------------------------------------------------------------------------
2 * C-Pluff, a plug-in framework for C
3 * Copyright 2007 Johannes Lehtinen
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a
6 * copy of this software and associated documentation files (the "Software"),
7 * to deal in the Software without restriction, including without limitation
8 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
9 * and/or sell copies of the Software, and to permit persons to whom the
10 * Software is furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included
13 * in all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
16 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
19 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
20 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
21 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 *-----------------------------------------------------------------------*/
23
24/** @file
25 * C-Pluff C API header file.
26 * The elements declared here constitute the C-Pluff C API. To use the
27 * API include this file and link the main program and plug-in runtime
28 * libraries with the C-Pluff C library. In addition to local declarations,
29 * this file also includes cpluffdef.h header file for defines common to C
30 * and C++ API.
31 */
32
33#ifndef CPLUFF_H_
34#define CPLUFF_H_
35
36/**
37 * @defgroup cDefines Defines
38 * Preprocessor defines.
39 */
40
41#include <cpluffdef.h>
42
43#ifdef __cplusplus
44extern "C" {
45#endif /*__cplusplus*/
46
47
48/* ------------------------------------------------------------------------
49 * Defines
50 * ----------------------------------------------------------------------*/
51
52/**
53 * @def CP_C_API
54 * @ingroup cDefines
55 *
56 * Marks a symbol declaration to be part of the C-Pluff C API.
57 * This macro declares the symbol to be imported from the C-Pluff library.
58 */
59
60#ifndef CP_C_API
61#define CP_C_API CP_IMPORT
62#endif
63
64
65/**
66 * @defgroup cScanFlags Flags for plug-in scanning
67 * @ingroup cDefines
68 *
69 * These constants can be orred together for the flags
70 * parameter of ::cp_scan_plugins.
71 */
72/*@{*/
73
74/**
75 * This flag enables upgrades of installed plug-ins by unloading
76 * the old version and installing the new version.
77 */
78#define CP_SP_UPGRADE 0x01
79
80/**
81 * This flag causes all plug-ins to be stopped before any
82 * plug-ins are to be upgraded.
83 */
84#define CP_SP_STOP_ALL_ON_UPGRADE 0x02
85
86/**
87 * This flag causes all plug-ins to be stopped before any
88 * plugins are to be installed (also if new version is to be installed
89 * as part of an upgrade).
90 */
91#define CP_SP_STOP_ALL_ON_INSTALL 0x04
92
93/**
94 * Setting this flag causes the currently active plug-ins to be restarted
95 * after all changes to the plug-ins have been made (if they were stopped).
96 */
97#define CP_SP_RESTART_ACTIVE 0x08
98
99/*@}*/
100
101
102/* ------------------------------------------------------------------------
103 * Data types
104 * ----------------------------------------------------------------------*/
105
106/**
107 * @defgroup cEnums Enumerations
108 * Constant value enumerations.
109 */
110
111/**
112 * @defgroup cTypedefs Typedefs
113 * Typedefs of various kind.
114 */
115
116/**
117 * @defgroup cStructs Data structures
118 * Data structure definitions.
119 */
120
121
122/* Enumerations */
123
124/**
125 * @ingroup cEnums
126 *
127 * An enumeration of status codes returned by API functions.
128 * Most of the interface functions return a status code. The returned
129 * status code either indicates successful completion of the operation
130 * or some specific kind of error. Some functions do not return a status
131 * code because they never fail.
132 */
134
135 /**
136 * Operation was performed successfully (equals to zero).
137 * @showinitializer
138 */
139 CP_OK = 0,
140
141 /** Not enough memory or other operating system resources available */
143
144 /** The specified object is unknown to the framework */
146
147 /** An I/O error occurred */
149
150 /** Malformed plug-in descriptor was encountered when loading a plug-in */
152
153 /** Plug-in or symbol conflicts with another plug-in or symbol. */
155
156 /** Plug-in dependencies could not be satisfied. */
158
159 /** Plug-in runtime signaled an error. */
161
163
164/**
165 * @ingroup cEnums
166 * An enumeration of possible plug-in states. Plug-in states are controlled
167 * by @ref cFuncsPlugin "plug-in management functions". Plug-in states can be
168 * observed by @ref cp_register_plistener "registering" a
169 * @ref cp_plugin_listener_func_t "plug-in listener function"
170 * or by calling ::cp_get_plugin_state.
171 *
172 * @sa cp_plugin_listener_t
173 * @sa cp_get_plugin_state
174 */
176
177 /**
178 * Plug-in is not installed. No plug-in information has been
179 * loaded.
180 */
182
183 /**
184 * Plug-in is installed. At this stage the plug-in information has
185 * been loaded but its dependencies to other plug-ins has not yet
186 * been resolved. The plug-in runtime has not been loaded yet.
187 * The extension points and extensions provided by the plug-in
188 * have been registered.
189 */
191
192 /**
193 * Plug-in dependencies have been resolved. At this stage it has
194 * been verified that the dependencies of the plug-in are satisfied
195 * and the plug-in runtime has been loaded but it is not active
196 * (it has not been started or it has been stopped).
197 * Plug-in is resolved when a dependent plug-in is being
198 * resolved or before the plug-in is started. Plug-in is put
199 * back to installed stage if its dependencies are being
200 * uninstalled.
201 */
203
204 /**
205 * Plug-in is starting. The plug-in has been resolved and the start
206 * function (if any) of the plug-in runtime is about to be called.
207 * A plug-in is started when explicitly requested by the main
208 * program or when a dependent plug-in is about to be started or when
209 * a dynamic symbol defined by the plug-in is being resolved. This state
210 * is omitted and the state changes directly from resolved to active
211 * if the plug-in runtime does not define a start function.
212 */
214
215 /**
216 * Plug-in is stopping. The stop function (if any) of the plug-in
217 * runtime is about to be called. A plug-in is stopped if the start
218 * function fails or when stopping is explicitly
219 * requested by the main program or when its dependencies are being
220 * stopped. This state is omitted and the state changes directly from
221 * active to resolved if the plug-in runtime does not define a stop
222 * function.
223 */
225
226 /**
227 * Plug-in has been successfully started and it has not yet been
228 * stopped.
229 */
231
233
234/**
235 * @ingroup cEnums
236 * An enumeration of possible message severities for framework logging. These
237 * constants are used when passing a log message to a
238 * @ref cp_logger_func_t "logger function" and when
239 * @ref cp_register_logger "registering" a logger function.
240 */
242
243 /** Used for detailed debug messages */
245
246 /** Used for informational messages such as plug-in state changes */
248
249 /** Used for messages warning about possible problems */
251
252 /** Used for messages reporting errors */
254
256
257/*@}*/
258
259
260/* Typedefs */
261
262/**
263 * @defgroup cTypedefsOpaque Opaque types
264 * @ingroup cTypedefs
265 * Opaque data type definitions.
266 */
267/*@{*/
268
269/**
270 * A plug-in context represents the co-operation environment of a set of
271 * plug-ins from the perspective of a particular participating plug-in or
272 * the perspective of the main program. It is used as an opaque handle to
273 * the shared resources but the framework also uses the context to identify
274 * the plug-in or the main program invoking framework functions. Therefore
275 * a plug-in should not generally expose its context instance to other
276 * plug-ins or the main program and neither should the main program
277 * expose its context instance to plug-ins. The main program creates
278 * plug-in contexts using ::cp_create_context and plug-ins receive their
279 * plug-in contexts via @ref cp_plugin_runtime_t::create.
280 */
282
283/*@}*/
284
285 /**
286 * @defgroup cTypedefsShorthand Shorthand type names
287 * @ingroup cTypedefs
288 * Shorthand type names for structs and enumerations.
289 */
290/*@{*/
291
292/** A type for cp_plugin_info_t structure. */
294
295/** A type for cp_plugin_import_t structure. */
297
298/** A type for cp_ext_point_t structure. */
300
301/** A type for cp_extension_t structure. */
303
304/** A type for cp_cfg_element_t structure. */
306
307/** A type for cp_plugin_runtime_t structure. */
309
310/** A type for cp_plugin_loader_t structure. */
312
313/** A type for cp_status_t enumeration. */
315
316/** A type for cp_plugin_state_t enumeration. */
318
319/** A type for cp_log_severity_t enumeration. */
321
322/*@}*/
323
324/**
325 * @defgroup cTypedefsFuncs Callback function types
326 * @ingroup cTypedefs
327 * Typedefs for client supplied callback functions.
328 */
329/*@{*/
330
331/**
332 * A listener function called synchronously after a plugin state change.
333 * The function should return promptly.
334 * @ref cFuncsInit "Library initialization",
335 * @ref cFuncsContext "plug-in context management",
336 * @ref cFuncsPlugin "plug-in management",
337 * listener registration (::cp_register_plistener and ::cp_unregister_plistener)
338 * and @ref cFuncsSymbols "dynamic symbol" functions must not be called from
339 * within a plug-in listener invocation. Listener functions are registered
340 * using ::cp_register_plistener.
341 *
342 * @param plugin_id the plug-in identifier
343 * @param old_state the old plug-in state
344 * @param new_state the new plug-in state
345 * @param user_data the user data pointer supplied at listener registration
346 */
347typedef void (*cp_plugin_listener_func_t)(const char *plugin_id, cp_plugin_state_t old_state, cp_plugin_state_t new_state, void *user_data);
348
349/**
350 * A logger function called to log selected plug-in framework messages. The
351 * messages may be localized. Plug-in framework API functions must not
352 * be called from within a logger function invocation. In a multi-threaded
353 * environment logger function invocations are serialized by the framework.
354 * Logger functions are registered using ::cp_register_logger.
355 *
356 * @param severity the severity of the message
357 * @param msg the message to be logged, possibly localized
358 * @param apid the identifier of the activating plug-in or NULL for the main program
359 * @param user_data the user data pointer given when the logger was registered
360 */
361typedef void (*cp_logger_func_t)(cp_log_severity_t severity, const char *msg, const char *apid, void *user_data);
362
363/**
364 * A fatal error handler for handling unrecoverable errors. If the error
365 * handler returns then the framework aborts the program. Plug-in framework
366 * API functions must not be called from within a fatal error handler
367 * invocation. The fatal error handler function is set using
368 * ::cp_set_fatal_error_handler.
369 *
370 * @param msg the possibly localized error message
371 */
372typedef void (*cp_fatal_error_func_t)(const char *msg);
373
374/**
375 * A run function registered by a plug-in to perform work.
376 * The run function should perform a finite chunk of work and it should
377 * return a non-zero value if there is more work to be done. Run functions
378 * are registered using ::cp_run_function and the usage is discussed in
379 * more detail in the @ref cFuncsPluginExec "serial execution" section.
380 *
381 * @param plugin_data the plug-in instance data pointer
382 * @return non-zero if there is more work to be done or zero if finished
383 */
384typedef int (*cp_run_func_t)(void *plugin_data);
385
386/*@}*/
387
388
389/* Data structures */
390
391/**
392 * @ingroup cStructs
393 * Plug-in information structure captures information about a plug-in. This
394 * information can be loaded from a plug-in descriptor using
395 * ::cp_load_plugin_descriptor. Information about installed plug-ins can
396 * be obtained using ::cp_get_plugin_info and ::cp_get_plugins_info. This
397 * structure corresponds to the @a plugin element in a plug-in descriptor.
398 */
400
401 /**
402 * The obligatory unique identifier of the plugin. A recommended way
403 * to generate identifiers is to use domain name service (DNS) prefixes
404 * (for example, org.cpluff.ExamplePlugin) to avoid naming conflicts. This
405 * corresponds to the @a id attribute of the @a plugin element in a plug-in
406 * descriptor.
407 */
409
410 /**
411 * An optional plug-in name. NULL if not available. The plug-in name is
412 * intended only for display purposes and the value can be localized.
413 * This corresponds to the @a name attribute of the @a plugin element in
414 * a plug-in descriptor.
415 */
416 char *name;
417
418 /**
419 * An optional release version string. NULL if not available. This
420 * corresponds to the @a version attribute of the @a plugin element in
421 * a plug-in descriptor.
422 */
423 char *version;
424
425 /**
426 * An optional provider name. NULL if not available. This is the name of
427 * the author or the organization providing the plug-in. The
428 * provider name is intended only for display purposes and the value can
429 * be localized. This corresponds to the @a provider-name attribute of the
430 * @a plugin element in a plug-in descriptor.
431 */
433
434 /**
435 * Path of the plugin directory or NULL if not known. This is the
436 * (absolute or relative) path to the plug-in directory containing
437 * plug-in data and the plug-in runtime library. The value corresponds
438 * to the path specified to ::cp_load_plugin_descriptor when loading
439 * the plug-in.
440 */
442
443 /**
444 * Optional ABI compatibility information. NULL if not available.
445 * This is the earliest version of the plug-in interface the current
446 * interface is backwards compatible with when it comes to the application
447 * binary interface (ABI) of the plug-in. That is, plug-in clients compiled against
448 * any plug-in interface version from @a abi_bw_compatibility to
449 * @ref version (inclusive) can use the current version of the plug-in
450 * binary. This describes binary or runtime compatibility.
451 * The value corresponds to the @a abi-compatibility
452 * attribute of the @a backwards-compatibility element in a plug-in descriptor.
453 */
455
456 /**
457 * Optional API compatibility information. NULL if not available.
458 * This is the earliest version of the plug-in interface the current
459 * interface is backwards compatible with when it comes to the
460 * application programming interface (API) of the plug-in. That is,
461 * plug-in clients written for any plug-in interface version from
462 * @a api_bw_compatibility to @ref version (inclusive) can be compiled
463 * against the current version of the plug-in API. This describes
464 * source or build time compatibility. The value corresponds to the
465 * @a api-compatibility attribute of the @a backwards-compatibility
466 * element in a plug-in descriptor.
467 */
469
470 /**
471 * Optional C-Pluff version requirement. NULL if not available.
472 * This is the version of the C-Pluff implementation the plug-in was
473 * compiled against. It is used to determine the compatibility of
474 * the plug-in runtime and the linked in C-Pluff implementation. Any
475 * C-Pluff version that is backwards compatible on binary level with the
476 * specified version fulfills the requirement.
477 */
479
480 /** Number of import entries in the @ref imports array. */
481 unsigned int num_imports;
482
483 /**
484 * An array of @ref num_imports import entries. These correspond to
485 * @a import elements in a plug-in descriptor.
486 */
488
489 /**
490 * The base name of the plug-in runtime library, or NULL if none.
491 * A platform specific prefix (for example, "lib") and an extension
492 * (for example, ".dll" or ".so") may be added to the base name.
493 * This corresponds to the @a library attribute of the
494 * @a runtime element in a plug-in descriptor.
495 */
497
498 /**
499 * The symbol pointing to the plug-in runtime function information or
500 * NULL if none. The symbol with this name should point to an instance of
501 * @ref cp_plugin_runtime_t structure. This corresponds to the
502 * @a funcs attribute of the @a runtime element in a plug-in descriptor.
503 */
505
506 /** Number of extension points in @ref ext_points array. */
507 unsigned int num_ext_points;
508
509 /**
510 * An array of @ref num_ext_points extension points provided by this
511 * plug-in. These correspond to @a extension-point elements in a
512 * plug-in descriptor.
513 */
515
516 /** Number of extensions in @ref extensions array. */
517 unsigned int num_extensions;
518
519 /**
520 * An array of @ref num_extensions extensions provided by this
521 * plug-in. These correspond to @a extension elements in a plug-in
522 * descriptor.
523 */
525
526};
527
528/**
529 * @ingroup cStructs
530 * Information about plug-in import. Plug-in import structures are
531 * contained in @ref cp_plugin_info_t::imports.
532 */
534
535 /**
536 * The identifier of the imported plug-in. This corresponds to the
537 * @a plugin attribute of the @a import element in a plug-in descriptor.
538 */
540
541 /**
542 * An optional version requirement. NULL if no version requirement.
543 * This is the version of the imported plug-in the importing plug-in was
544 * compiled against. Any version of the imported plug-in that is
545 * backwards compatible with this version fulfills the requirement.
546 * This corresponds to the @a if-version attribute of the @a import
547 * element in a plug-in descriptor.
548 */
549 char *version;
550
551 /**
552 * Is this import optional. 1 for optional and 0 for mandatory import.
553 * An optional import causes the imported plug-in to be started if it is
554 * available but does not stop the importing plug-in from starting if the
555 * imported plug-in is not available. If the imported plug-in is available
556 * but the API version conflicts with the API version requirement then the
557 * importing plug-in fails to start. This corresponds to the @a optional
558 * attribute of the @a import element in a plug-in descriptor.
559 */
561};
562
563/**
564 * @ingroup cStructs
565 * Extension point structure captures information about an extension
566 * point. Extension point structures are contained in
567 * @ref cp_plugin_info_t::ext_points.
568 */
570
571 /**
572 * A pointer to plug-in information containing this extension point.
573 * This reverse pointer is provided to make it easy to get information
574 * about the plug-in which is hosting a particular extension point.
575 */
577
578 /**
579 * The local identifier uniquely identifying the extension point within the
580 * host plug-in. This corresponds to the @name id attribute of an
581 * @a extension-point element in a plug-in descriptor.
582 */
583 char *local_id;
584
585 /**
586 * The unique identifier of the extension point. This is automatically
587 * constructed by concatenating the identifier of the host plug-in and
588 * the local identifier of the extension point.
589 */
591
592 /**
593 * An optional extension point name. NULL if not available. The extension
594 * point name is intended for display purposes only and the value can be
595 * localized. This corresponds to the @a name attribute of
596 * an @a extension-point element in a plug-in descriptor.
597 */
598 char *name;
599
600 /**
601 * An optional path to the extension schema definition.
602 * NULL if not available. The path is relative to the plug-in directory.
603 * This corresponds to the @a schema attribute
604 * of an @a extension-point element in a plug-in descriptor.
605 */
607};
608
609/**
610 * @ingroup cStructs
611 * Extension structure captures information about an extension. Extension
612 * structures are contained in @ref cp_plugin_info_t::extensions.
613 */
615
616 /**
617 * A pointer to plug-in information containing this extension.
618 * This reverse pointer is provided to make it easy to get information
619 * about the plug-in which is hosting a particular extension.
620 */
622
623 /**
624 * The unique identifier of the extension point this extension is
625 * attached to. This corresponds to the @a point attribute of an
626 * @a extension element in a plug-in descriptor.
627 */
629
630 /**
631 * An optional local identifier uniquely identifying the extension within
632 * the host plug-in. NULL if not available. This corresponds to the
633 * @a id attribute of an @a extension element in a plug-in descriptor.
634 */
635 char *local_id;
636
637 /**
638 * An optional unique identifier of the extension. NULL if not available.
639 * This is automatically constructed by concatenating the identifier
640 * of the host plug-in and the local identifier of the extension.
641 */
643
644 /**
645 * An optional extension name. NULL if not available. The extension name
646 * is intended for display purposes only and the value can be localized.
647 * This corresponds to the @a name attribute
648 * of an @a extension element in a plug-in descriptor.
649 **/
650 char *name;
651
652 /**
653 * Extension configuration starting with the extension element.
654 * This includes extension configuration information as a tree of
655 * configuration elements. These correspond to the @a extension
656 * element and its contents in a plug-in descriptor.
657 */
659};
660
661/**
662 * @ingroup cStructs
663 * A configuration element contains configuration information for an
664 * extension. Utility functions ::cp_lookup_cfg_element and
665 * ::cp_lookup_cfg_value can be used for traversing the tree of
666 * configuration elements. Pointer to the root configuration element is
667 * stored at @ref cp_extension_t::configuration and others are contained as
668 * @ref cp_cfg_element_t::children "children" of parent elements.
669 */
671
672 /**
673 * The name of the configuration element. This corresponds to the name of
674 * the element in a plug-in descriptor.
675 */
676 char *name;
677
678 /** Number of attribute name, value pairs in the @ref atts array. */
679 unsigned int num_atts;
680
681 /**
682 * An array of pointers to alternating attribute names and values.
683 * Attribute values can be localized.
684 */
685 char **atts;
686
687 /**
688 * An optional value of this configuration element. NULL if not available.
689 * The value can be localized. This corresponds to the
690 * text contents of the element in a plug-in descriptor.
691 */
692 char *value;
693
694 /** A pointer to the parent element or NULL if this is a root element. */
696
697 /** The index of this element among its siblings (0-based). */
698 unsigned int index;
699
700 /** Number of children in the @ref children array. */
701 unsigned int num_children;
702
703 /**
704 * An array of @ref num_children childrens of this element. These
705 * correspond to child elements in a plug-in descriptor.
706 */
708};
709
710/**
711 * @ingroup cStructs
712 * Container for plug-in runtime information. A plug-in runtime defines a
713 * static instance of this structure to pass information to the plug-in
714 * framework. The plug-in framework then uses the information
715 * to create and control plug-in instances. The symbol pointing
716 * to the runtime information instance is named by the @a funcs
717 * attribute of the @a runtime element in a plug-in descriptor.
718 *
719 * The following graph displays how these functions are used to control the
720 * state of the plug-in instance.
721 *
722 * @dot
723 * digraph lifecycle {
724 * rankdir=LR;
725 * node [shape=ellipse, fontname=Helvetica, fontsize=10];
726 * edge [fontname=Helvetica, fontsize=10];
727 * none [label="no instance"];
728 * inactive [label="inactive"];
729 * active [label="active"];
730 * none -> inactive [label="create", URL="\ref create"];
731 * inactive -> active [label="start", URL="\ref start"];
732 * active -> inactive [label="stop", URL="\ref stop"];
733 * inactive -> none [label="destroy", URL="\ref destroy"];
734 * }
735 * @enddot
736 */
738
739 /**
740 * An initialization function called to create a new plug-in
741 * runtime instance. The initialization function initializes and
742 * returns an opaque plug-in instance data pointer which is then
743 * passed on to other control functions. This data pointer should
744 * be used to access plug-in instance specific data. For example,
745 * the context reference must be stored as part of plug-in instance
746 * data if the plug-in runtime needs it. On failure, this function
747 * must return NULL.
748 *
749 * C-Pluff API functions must not be called from within a create
750 * function invocation and symbols from imported plug-ins must not be
751 * used because they may not available yet.
752 *
753 * @param ctx the plug-in context of the new plug-in instance
754 * @return an opaque pointer to plug-in instance data or NULL on failure
755 */
756 void *(*create)(cp_context_t *ctx);
757
758 /**
759 * A start function called to start a plug-in instance.
760 * The start function must return zero (CP_OK) on success and non-zero
761 * on failure. If the start fails then the stop function (if any) is
762 * called to clean up plug-in state. @ref cFuncsInit "Library initialization",
763 * @ref cFuncsContext "plug-in context management" and
764 * @ref cFuncsPlugin "plug-in management" functions must not be
765 * called from within a start function invocation. The start function
766 * pointer can be NULL if the plug-in runtime does not have a start
767 * function.
768 *
769 * The start function implementation should set up plug-in and return
770 * promptly. If there is further work to be done then a plug-in can
771 * start a thread or register a run function using ::cp_run_function.
772 * Symbols from imported plug-ins are guaranteed to be available for
773 * the start function.
774 *
775 * @param data an opaque pointer to plug-in instance data
776 * @return non-zero on success, or zero on failure
777 */
778 int (*start)(void *data);
779
780 /**
781 * A stop function called to stop a plugin instance.
782 * This function must cease all plug-in runtime activities.
783 * @ref cFuncsInit "Library initialization",
784 * @ref cFuncsContext "plug-in context management",
785 * @ref cFuncsPlugin "plug-in management"
786 * functions, ::cp_run_function and ::cp_resolve_symbol must not be called
787 * from within a stop function invocation. The stop function pointer can
788 * be NULL if the plug-in runtime does not have a stop function.
789 * It is guaranteed that no run functions registered by the plug-in are
790 * called simultaneously or after the call to the stop function.
791 *
792 * The stop function should release any external resources hold by
793 * the plug-in. Dynamically resolved symbols are automatically released
794 * and dynamically defined symbols and registered run functions are
795 * automatically unregistered after the call to stop function.
796 * Resolved external symbols are still available for the stop function
797 * and symbols provided by the plug-in should remain available
798 * after the call to stop function (although functionality might be
799 * limited). Final cleanup can be safely done in the destroy function.
800 *
801 * @param data an opaque pointer to plug-in instance data
802 */
803 void (*stop)(void *data);
804
805 /**
806 * A destroy function called to destroy a plug-in instance.
807 * This function should release any plug-in instance data.
808 * The plug-in is stopped before this function is called.
809 * C-Pluff API functions must not be called from within a destroy
810 * function invocation and symbols from imported plug-ins must not be
811 * used because they may not be available anymore. Correspondingly,
812 * it is guaranteed that the symbols provided by the plug-in are not
813 * used by other plug-ins when destroy function has been called.
814 *
815 * @param data an opaque pointer to plug-in instance data
816 */
817 void (*destroy)(void *data);
818
819};
820
821/**
822 * @ingroup cStructs
823 * A plug-in loader instance. Plug-in loaders are responsible for
824 * loading plug-in information from plug-in collections and providing it
825 * to the framework. The loader exposes its services to the
826 * framework via an instance of this structure which is obtained from a
827 * loader-specific constructor function.
828 *
829 * @ref cFuncsInit "Library initialization" and
830 * @ref cFuncsContext "plug-in context management"
831 * functions must not be called from within the service functions stored
832 * in this structure.
833 *
834 * The framework itself provides a plug-in loader capable of loading plugins
835 * from a local plug-in collection (a directory containing plugins).
836 * However, applications may provide custom plug-in loaders, for example to
837 * load plug-ins from remote plug-in collections.
838 */
840
841 /**
842 * An opaque data pointer for this plug-in loader instance. This data
843 * pointer is passed on to service functions specified by this
844 * structure. The loader-specific constructor initializes it to
845 * instance-specific data such as configuration of the plug-in collection.
846 */
847 void *data;
848
849 /**
850 * A function called to load plug-in information from the configured
851 * plug-in collection. Loads and returns plug-in descriptors for
852 * compatible plug-ins found in the plug-in collection. The returned
853 * plug-in information must be loaded using ::cp_load_plugin_descriptor.
854 * This function is called when ::cp_scan_plugins is called. The data
855 * returned by this function is released by calling the
856 * @a release_plugins function when the array is not needed anymore.
857 * This function returns NULL on failure.
858 *
859 * The runtime code and data of the returned plug-ins does not need to
860 * be locally available. The @a resolve_files function is explicitly
861 * called when the runtime code and data is needed. The plug-in
862 * path must be initialized into a location that will hold the plug-in
863 * code and data after the plug-in has been resolved. In practice this
864 * means that the plug-in descriptor must be loaded from a path that will
865 * hold plug-in and data after the plug-in has been resolved.
866 *
867 * @param data plug-in loader data
868 * @param ctx the associatd plug-in context
869 * @return pointer to a NULL-terminated array of plug-in information pointers, or NULL on failure
870 */
871 cp_plugin_info_t **(*scan_plugins)(void *data, cp_context_t *ctx);
872
873 /**
874 * A function called to ensure that the plug-in runtime code and data
875 * is locally available. Makes the runtime code and data of the specified
876 * plug-in available at the plug-in path. The specified plug-in has been
877 * obtained from a call to @a scan_plugins. Does nothing if the plug-in
878 * runtime data is already locally available. This function may be NULL
879 * if plug-ing runtime data is always available after successful scan.
880 *
881 * @param data plug-in loader data
882 * @param ctx the associated plug-in context
883 * @param plugin plug-in information for the plug-in being resolved
884 * @return non-zero on success or zero on failure
885 */
886 int (*resolve_files)(void *data, cp_context_t *ctx, cp_plugin_info_t *plugin);
887
888 /**
889 * A function called to release plug-in information returned by the
890 * @a scan_plugins function. This function must call ::cp_release_info
891 * on each plug-in information structure and deallocate the pointer array.
892 * If this function is NULL, the framework will release plug-in
893 * information structures and deallocate the pointer array using
894 * @a free.
895 *
896 * @param data plug-in loader data
897 * @param ctx the associated plug-in context
898 * @param plugins pointer to a NULL-terminated array of plug-in information pointers obtained from a call to scan_plugins
899 */
900 void (*release_plugins)(void *data, cp_context_t *ctx, cp_plugin_info_t **plugins);
901
902};
903
904/*@}*/
905
906
907/* ------------------------------------------------------------------------
908 * Function declarations
909 * ----------------------------------------------------------------------*/
910
911/**
912 * @defgroup cFuncs Functions
913 *
914 * C API functions. The C-Pluff C API functions and
915 * any data exposed by them are generally thread-safe if the library has been
916 * compiled with multi-threading support. The
917 * @ref cFuncsInit "framework initialization functions"
918 * are exceptions, they are not thread-safe.
919 */
920
921/**
922 * @defgroup cFuncsFrameworkInfo Framework information
923 * @ingroup cFuncs
924 *
925 * These functions can be used to query runtime information about the
926 * linked in C-Pluff implementation. They may be used by the main program or
927 * by a plug-in runtime.
928 */
929/*@{*/
930
931/**
932 * Returns the release version string of the linked in C-Pluff
933 * implementation.
934 *
935 * @return the C-Pluff release version string
936 */
938
939/**
940 * Returns the canonical host type associated with the linked in C-Pluff implementation.
941 * A multi-platform installation manager could use this information to
942 * determine what plug-in versions to install.
943 *
944 * @return the canonical host type
945 */
947
948/*@}*/
949
950
951/**
952 * @defgroup cFuncsInit Framework initialization
953 * @ingroup cFuncs
954 *
955 * These functions are used for framework initialization.
956 * They are intended to be used by the main program. These functions are
957 * not thread safe.
958 */
959/*@{*/
960
961/**
962 * Sets the fatal error handler called on non-recoverable errors. The default
963 * error handler prints the error message out to standard error and aborts
964 * the program. If the user specified error handler returns then the framework
965 * will abort the program. Setting NULL error handler will restore the default
966 * handler. This function is not thread-safe and it should be called
967 * before initializing the framework to catch all fatal errors.
968 *
969 * @param error_handler the fatal error handler
970 */
972
973/**
974 * Initializes the plug-in framework. This function must be called
975 * by the main program before calling any other plug-in framework
976 * functions except @ref cFuncsFrameworkInfo "framework information" functions and
977 * ::cp_set_fatal_error_handler. This function may be
978 * called several times but it is not thread-safe. Library resources
979 * should be released by calling ::cp_destroy when the framework is
980 * not needed anymore.
981 *
982 * Additionally, to enable localization support, the main program should
983 * set the current locale using @code setlocale(LC_ALL, "") @endcode
984 * before calling this function.
985 *
986 * @return @ref CP_OK (zero) on success or error code on failure
987 */
989
990/**
991 * Destroys the plug-in framework and releases the resources used by it.
992 * The plug-in framework is only destroyed after this function has
993 * been called as many times as ::cp_init. This function is not
994 * thread-safe. Plug-in framework functions other than ::cp_init,
995 * ::cp_get_framework_info and ::cp_set_fatal_error_handler
996 * must not be called after the plug-in framework has been destroyed.
997 * All contexts are destroyed and all data references returned by the
998 * framework become invalid.
999 */
1001
1002/*@}*/
1003
1004
1005/**
1006 * @defgroup cFuncsContext Plug-in context initialization
1007 * @ingroup cFuncs
1008 *
1009 * These functions are used to manage plug-in contexts from the main
1010 * program perspective. They are not intended to be used by a plug-in runtime.
1011 * From the main program perspective a plug-in context is a container for
1012 * installed plug-ins. There can be several plug-in context instances if there
1013 * are several independent sets of plug-ins. However, different plug-in
1014 * contexts are not very isolated from each other in practice because the
1015 * global symbols exported by a plug-in runtime in one context are visible to
1016 * all plug-ins in all context instances.
1017 */
1018/*@{*/
1019
1020/**
1021 * Creates a new plug-in context which can be used as a container for plug-ins.
1022 * Plug-ins are loaded and installed into a specific context. The main
1023 * program may have more than one plug-in context but the plug-ins that
1024 * interact with each other should be placed in the same context. The
1025 * resources associated with the context are released by calling
1026 * ::cp_destroy_context when the context is not needed anymore. Remaining
1027 * contexts are automatically destroyed when the plug-in framework is
1028 * destroyed.
1029 *
1030 * @param status pointer to the location where status code is to be stored, or NULL
1031 * @return the newly created plugin context, or NULL on failure
1032 */
1034
1035/**
1036 * Changes the file name in the plug-in the plug-in descriptor is loaded from.
1037 * The default name is "plugin.xml"
1038 *
1039 * @param ctx the context to change the plug-in descriptor file name in
1040 * @param name the new plug-in descriptor file name
1041 */
1043
1044/**
1045 * Changes the XML root element's name in plug-in descriptor.
1046 * This also changes the attribute name to be used in the "import" element.
1047 * The default name is "plugin".
1048 *
1049 * @param ctx the context to change the plug-in descriptor's XML root element's name in
1050 * @param root the new XML root element name
1051 */
1053
1054/**
1055 * Destroys the specified plug-in context and releases the associated resources.
1056 * Stops and uninstalls all plug-ins in the context. The context must not be
1057 * accessed after calling this function.
1058 *
1059 * @param ctx the context to be destroyed
1060 */
1062
1063/**
1064 * Registers a local plug-in collection with a plug-in context. A local plug-in collection
1065 * is a directory that has plug-ins as its immediate subdirectories. The
1066 * plug-in context will scan the directory when ::cp_scan_plugins is called.
1067 * Returns @ref CP_OK if the directory has already been registered. A plug-in
1068 * collection can be unregistered using ::cp_unregister_pcollection or
1069 * ::cp_unregister_pcollections.
1070 *
1071 * This is equivalent to having registered a local plug-in loader and
1072 * registering a plug-in directory with it.
1073 *
1074 * @param ctx the plug-in context
1075 * @param dir the directory
1076 * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if insufficient memory
1077 */
1079
1080/**
1081 * Unregisters a previously registered plug-in collection from a
1082 * plug-in context. Plug-ins already loaded from the collection are not
1083 * affected. Does nothing if the directory has not been registered.
1084 * Plug-in collections can be registered using ::cp_register_pcollection.
1085 *
1086 * This is equivalent to having registered a local plug-in loader and
1087 * unregistering a plug-in directory with it.
1088 *
1089 * @param ctx the plug-in context
1090 * @param dir the previously registered directory
1091 */
1093
1094/**
1095 * Unregisters all plug-in collections from a plug-in context.
1096 * Plug-ins already loaded are not affected. Plug-in collections can
1097 * be registered using ::cp_register_pcollection.
1098 *
1099 * This is equivalent to having registered a local plug-in loader and
1100 * unregistering all plug-in directories with it.
1101 *
1102 * @param ctx the plug-in context
1103 */
1105
1106/**
1107 * Registers a plug-in loader that will be used to load plug-ins into this
1108 * context when ::cp_scan_plugins is called. Several plug-in loaders can be
1109 * registered for a context. Returns @ref CP_OK if the same loader instance
1110 * has already been registered with the context. A loader can be unregistered
1111 * using ::cp_unregister_ploader or ::cp_unregister_ploaders. An alternative
1112 * to explicitly registering a plug-in loader is to register a local plug-in
1113 * collection
1114 *
1115 * @param ctx the plug-in context
1116 * @param loader the plug-in loader
1117 * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if insufficient memory
1118 */
1120
1121/**
1122 * Unregisters a previously registered plug-in loader from a plug-in context.
1123 * All plug-ins loaded by the loader are uninstalled. Does nothing if the
1124 * specified loader has not been registered. Plug-in loaders can be registered
1125 * using ::cp_register_ploader.
1126 *
1127 * @param ctx the plug-in context
1128 * @param loader the plug-in loader
1129 */
1131
1132/**
1133 * Unregisters all registered plug-in loaders from a plug-in context.
1134 * All plug-ins loaded by the unregistered loaders are uninstalled. Plug-in
1135 * loaders can be registered using ::cp_register_ploader.
1136 *
1137 * @param ctx the plug-in context
1138 */
1140
1141/*@}*/
1142
1143
1144/**
1145 * @defgroup cFuncsLogging Logging
1146 * @ingroup cFuncs
1147 *
1148 * These functions can be used to receive and emit log messages related
1149 * to a particular plug-in context. They can be used by the main program
1150 * or by a plug-in runtime.
1151 */
1152/*@{*/
1153
1154/**
1155 * Registers a logger with a plug-in context or updates the settings of a
1156 * registered logger. The logger will receive selected log messages.
1157 * If the specified logger is not yet known, a new logger registration
1158 * is made, otherwise the settings for the existing logger are updated.
1159 * The logger can be unregistered using ::cp_unregister_logger and it is
1160 * automatically unregistered when the registering plug-in is stopped or
1161 * when the context is destroyed.
1162 *
1163 * @param ctx the plug-in context to log
1164 * @param logger the logger function to be called
1165 * @param user_data the user data pointer passed to the logger
1166 * @param min_severity the minimum severity of messages passed to logger
1167 * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if insufficient memory
1168 */
1170
1171/**
1172 * Removes a logger registration.
1173 *
1174 * @param ctx the plug-in context
1175 * @param logger the logger function to be unregistered
1176 */
1178
1179/**
1180 * Emits a new log message.
1181 *
1182 * @param ctx the plug-in context
1183 * @param severity the severity of the event
1184 * @param msg the log message (possibly localized)
1185 */
1186CP_C_API void cp_log(cp_context_t *ctx, cp_log_severity_t severity, const char *msg) CP_GCC_NONNULL(1, 3);
1187
1188/**
1189 * Returns whether a message of the specified severity would get logged.
1190 *
1191 * @param ctx the plug-in context
1192 * @param severity the target logging severity
1193 * @return whether a message of the specified severity would get logged
1194 */
1196
1197/*@}*/
1198
1199
1200/**
1201 * @defgroup cFuncsPlugin Plug-in management
1202 * @ingroup cFuncs
1203 *
1204 * These functions can be used to manage plug-ins. They are intended to be
1205 * used by the main program.
1206 */
1207/*@{*/
1208
1209/**
1210 * Loads a plug-in descriptor from the specified plug-in installation
1211 * path and returns information about the plug-in. The plug-in descriptor
1212 * is validated during loading. Possible loading errors are reported via the
1213 * specified plug-in context. The plug-in is not installed to the context.
1214 * If operation fails or the descriptor
1215 * is invalid then NULL is returned. The caller must release the returned
1216 * information by calling ::cp_release_info when it does not
1217 * need the information anymore, typically after installing the plug-in.
1218 * The returned plug-in information must not be modified.
1219 *
1220 * @param ctx the plug-in context
1221 * @param path the installation path of the plug-in
1222 * @param status a pointer to the location where status code is to be stored, or NULL
1223 * @return pointer to the information structure or NULL if error occurs
1224 */
1226
1227/**
1228 * Loads a plug-in descriptor from the specified block of memory and returns
1229 * information about the plug-in. The plug-in descriptor
1230 * is validated during loading. Possible loading errors are reported via the
1231 * specified plug-in context. The plug-in is not installed to the context.
1232 * If operation fails or the descriptor
1233 * is invalid then NULL is returned. The caller must release the returned
1234 * information by calling ::cp_release_info when it does not
1235 * need the information anymore, typically after installing the plug-in.
1236 * The returned plug-in information must not be modified.
1237 *
1238 * @param ctx the plug-in context
1239 * @param buffer the buffer containing the plug-in descriptor.
1240 * @param buffer_len the length of the buffer.
1241 * @param status a pointer to the location where status code is to be stored, or NULL
1242 * @return pointer to the information structure or NULL if error occurs
1243 */
1244CP_C_API cp_plugin_info_t * cp_load_plugin_descriptor_from_memory(cp_context_t *ctx, const char *buffer, unsigned int buffer_len, cp_status_t *status) CP_GCC_NONNULL(1, 2);
1245
1246/**
1247 * Installs the plug-in described by the specified plug-in information
1248 * structure to the specified plug-in context. The plug-in information
1249 * must have been loaded using ::cp_load_plugin_descriptor with the same
1250 * plug-in context.
1251 * The installation fails on #CP_ERR_CONFLICT if the context already
1252 * has an installed plug-in with the same plug-in identifier. Installation
1253 * also fails if the plug-in tries to install an extension point which
1254 * conflicts with an already installed extension point.
1255 * The plug-in information must not be modified but it is safe to call
1256 * ::cp_release_info after the plug-in has been installed.
1257 *
1258 * @param ctx the plug-in context
1259 * @param pi plug-in information structure
1260 * @return @ref CP_OK (zero) on success or an error code on failure
1261 */
1263
1264/**
1265 * Scans for plug-ins in the registered plug-in directories, installing
1266 * new plug-ins and upgrading installed plug-ins. This function can be used to
1267 * initially load the plug-ins and to later rescan for new plug-ins.
1268 *
1269 * When several versions of the same plug-in is available the most recent
1270 * version will be installed. The upgrade behavior depends on the specified
1271 * @ref cScanFlags "flags". If #CP_SP_UPGRADE is set then upgrades to installed plug-ins are
1272 * allowed. The old version is unloaded and the new version installed instead.
1273 * If #CP_SP_STOP_ALL_ON_UPGRADE is set then all active plug-ins are stopped
1274 * if any plug-ins are to be upgraded. If #CP_SP_STOP_ALL_ON_INSTALL is set then
1275 * all active plug-ins are stopped if any plug-ins are to be installed or
1276 * upgraded. Finally, if #CP_SP_RESTART_ACTIVE is set all currently active
1277 * plug-ins will be restarted after the changes (if they were stopped).
1278 *
1279 * When removing plug-in files from the plug-in directories, the
1280 * plug-ins to be removed must be first unloaded. Therefore this function
1281 * does not check for removed plug-ins.
1282 *
1283 * @param ctx the plug-in context
1284 * @param flags the bitmask of flags
1285 * @return @ref CP_OK (zero) on success or an error code on failure
1286 */
1288
1289/**
1290 * Starts a plug-in. Also starts any imported plug-ins. If the plug-in is
1291 * already starting then
1292 * this function blocks until the plug-in has started or failed to start.
1293 * If the plug-in is already active then this function returns immediately.
1294 * If the plug-in is stopping then this function blocks until the plug-in
1295 * has stopped and then starts the plug-in.
1296 *
1297 * @param ctx the plug-in context
1298 * @param id identifier of the plug-in to be started
1299 * @return @ref CP_OK (zero) on success or an error code on failure
1300 */
1302
1303/**
1304 * Stops a plug-in. First stops any dependent plug-ins that are currently
1305 * active. Then stops the specified plug-in. If the plug-in is already
1306 * stopping then this function blocks until the plug-in has stopped. If the
1307 * plug-in is already stopped then this function returns immediately. If the
1308 * plug-in is starting then this function blocks until the plug-in has
1309 * started (or failed to start) and then stops the plug-in.
1310 *
1311 * @param ctx the plug-in context
1312 * @param id identifier of the plug-in to be stopped
1313 * @return @ref CP_OK (zero) on success or @ref CP_ERR_UNKNOWN if unknown plug-in
1314 */
1316
1317/**
1318 * Stops all active plug-ins.
1319 *
1320 * @param ctx the plug-in context
1321 */
1323
1324/**
1325 * Uninstalls the specified plug-in. The plug-in is first stopped if it is active.
1326 * Then uninstalls the plug-in and any dependent plug-ins.
1327 *
1328 * @param ctx the plug-in context
1329 * @param id identifier of the plug-in to be unloaded
1330 * @return @ref CP_OK (zero) on success or @ref CP_ERR_UNKNOWN if unknown plug-in
1331 */
1333
1334/**
1335 * Uninstalls all plug-ins. All plug-ins are first stopped and then
1336 * uninstalled.
1337 *
1338 * @param ctx the plug-in context
1339 */
1341
1342/*@}*/
1343
1344
1345/**
1346 * @defgroup cFuncsPluginInfo Plug-in and extension information
1347 * @ingroup cFuncs
1348 *
1349 * These functions can be used to query information about the installed
1350 * plug-ins, extension points and extensions or to listen for plug-in state
1351 * changes. They may be used by the main program or by a plug-in runtime.
1352 */
1353/*@{*/
1354
1355/**
1356 * Returns static information about the specified plug-in. The returned
1357 * information must not be modified and the caller must
1358 * release the information by calling ::cp_release_info when the
1359 * information is not needed anymore. When a plug-in runtime calls this
1360 * function it may pass NULL as the identifier to get information about the
1361 * plug-in itself.
1362 *
1363 * @param ctx the plug-in context
1364 * @param id identifier of the plug-in to be examined or NULL for self
1365 * @param status a pointer to the location where status code is to be stored, or NULL
1366 * @return pointer to the information structure or NULL on failure
1367 */
1369
1370/**
1371 * Returns static information about the installed plug-ins. The returned
1372 * information must not be modified and the caller must
1373 * release the information by calling ::cp_release_info when the
1374 * information is not needed anymore.
1375 *
1376 * @param ctx the plug-in context
1377 * @param status a pointer to the location where status code is to be stored, or NULL
1378 * @param num a pointer to the location where the number of returned plug-ins is stored, or NULL
1379 * @return pointer to a NULL-terminated list of pointers to plug-in information
1380 * or NULL on failure
1381 */
1383
1384/**
1385 * Returns static information about the currently installed extension points.
1386 * The returned information must not be modified and the caller must
1387 * release the information by calling ::cp_release_info when the
1388 * information is not needed anymore.
1389 *
1390 * @param ctx the plug-in context
1391 * @param status a pointer to the location where status code is to be stored, or NULL
1392 * @param num filled with the number of returned extension points, if non-NULL
1393 * @return pointer to a NULL-terminated list of pointers to extension point
1394 * information or NULL on failure
1395 */
1397
1398/**
1399 * Returns static information about the currently installed extension points.
1400 * The returned information must not be modified and the caller must
1401 * release the information by calling ::cp_release_info when the
1402 * information is not needed anymore.
1403 *
1404 * @param ctx the plug-in context
1405 * @param extpt_id the extension point identifier or NULL for all extensions
1406 * @param status a pointer to the location where status code is to be stored, or NULL
1407 * @param num a pointer to the location where the number of returned extension points is to be stored, or NULL
1408 * @return pointer to a NULL-terminated list of pointers to extension
1409 * information or NULL on failure
1410 */
1411CP_C_API cp_extension_t ** cp_get_extensions_info(cp_context_t *ctx, const char *extpt_id, cp_status_t *status, int *num) CP_GCC_NONNULL(1);
1412
1413/**
1414 * Releases a previously obtained reference counted information object. The
1415 * documentation for functions returning such information refers
1416 * to this function. The information must not be accessed after it has
1417 * been released. The framework uses reference counting to deallocate
1418 * the information when it is not in use anymore.
1419 *
1420 * @param ctx the plug-in context
1421 * @param info the information to be released
1422 */
1424
1425/**
1426 * Returns the current state of the specified plug-in. Returns
1427 * #CP_PLUGIN_UNINSTALLED if the specified plug-in identifier is unknown.
1428 *
1429 * @param ctx the plug-in context
1430 * @param id the plug-in identifier
1431 * @return the current state of the plug-in
1432 */
1434
1435/**
1436 * Registers a plug-in listener with a plug-in context. The listener is called
1437 * synchronously immediately after a plug-in state change. There can be several
1438 * listeners registered with the same context. A plug-in listener can be
1439 * unregistered using ::cp_unregister_plistener and it is automatically
1440 * unregistered when the registering plug-in is stopped or when the context
1441 * is destroyed.
1442 *
1443 * @param ctx the plug-in context
1444 * @param listener the plug-in listener to be added
1445 * @param user_data user data pointer supplied to the listener
1446 * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if out of resources
1447 */
1449
1450/**
1451 * Removes a plug-in listener from a plug-in context. Does nothing if the
1452 * specified listener was not registered.
1453 *
1454 * @param ctx the plug-in context
1455 * @param listener the plug-in listener to be removed
1456 */
1458
1459/**
1460 * Traverses a configuration element tree and returns the specified element.
1461 * The target element is specified by a base element and a relative path from
1462 * the base element to the target element. The path includes element names
1463 * separated by slash '/'. Two dots ".." can be used to designate a parent
1464 * element. Returns NULL if the specified element does not exist. If there are
1465 * several subelements with the same name, this function chooses the first one
1466 * when traversing the tree.
1467 *
1468 * @param base the base configuration element
1469 * @param path the path to the target element
1470 * @return the target element or NULL if nonexisting
1471 */
1473
1474/**
1475 * Traverses a configuration element tree and returns the value of the
1476 * specified element or attribute. The target element or attribute is specified
1477 * by a base element and a relative path from the base element to the target
1478 * element or attributes. The path includes element names
1479 * separated by slash '/'. Two dots ".." can be used to designate a parent
1480 * element. The path may end with '@' followed by an attribute name
1481 * to select an attribute. Returns NULL if the specified element or attribute
1482 * does not exist or does not have a value. If there are several subelements
1483 * with the same name, this function chooses the first one when traversing the
1484 * tree.
1485 *
1486 * @param base the base configuration element
1487 * @param path the path to the target element
1488 * @return the value of the target element or attribute or NULL
1489 */
1491
1492/*@}*/
1493
1494
1495/**
1496 * @defgroup cFuncsPluginExec Plug-in execution
1497 * @ingroup cFuncs
1498 *
1499 * These functions support a plug-in controlled execution model. Started plug-ins can
1500 * use ::cp_run_function to register @ref cp_run_func_t "a run function" which is called when the
1501 * main program calls ::cp_run_plugins or ::cp_run_plugins_step. A run
1502 * function should do a finite chunk of work and then return telling whether
1503 * there is more work to be done. A run function is automatically unregistered
1504 * when the plug-in is stopped. Run functions make it possible for plug-ins
1505 * to control the flow of execution or they can be used as a coarse
1506 * way of task switching if there is no multi-threading support.
1507 *
1508 * The C-Pluff distribution includes a generic main program, cpluff-loader,
1509 * which only acts as a plug-in loader. It loads and starts up the
1510 * specified plug-ins, passing any additional startup arguments to them and
1511 * then just calls run functions of the plug-ins. This
1512 * makes it is possible to put all the application specific logic in
1513 * plug-ins. Application does not necessarily need a main program of its own.
1514 *
1515 * It is also safe, from framework perspective, to call these functions from
1516 * multiple threads. Run functions may then be executed in parallel threads.
1517 */
1518/*@{*/
1519
1520/**
1521 * Registers a new run function. The plug-in instance data pointer is given to
1522 * the run function as a parameter. The run function must return zero if it has
1523 * finished its work or non-zero if it should be called again later. The run
1524 * function is unregistered when it returns zero. Plug-in framework functions
1525 * stopping the registering plug-in must not be called from within a run
1526 * function. This function does nothing if the specified run
1527 * function is already registered for the calling plug-in instance.
1528 *
1529 * @param ctx the plug-in context of the registering plug-in
1530 * @param runfunc the run function to be registered
1531 * @return @ref CP_OK (zero) on success or an error code on failure
1532 */
1534
1535/**
1536 * Runs the started plug-ins as long as there is something to run.
1537 * This function calls repeatedly run functions registered by started plug-ins
1538 * until there are no more active run functions. This function is normally
1539 * called by a thin main proram, a loader, which loads plug-ins, starts some
1540 * plug-ins and then passes control over to the started plug-ins.
1541 *
1542 * @param ctx the plug-in context containing the plug-ins
1543 */
1545
1546/**
1547 * Runs one registered run function. This function calls one
1548 * active run function registered by a started plug-in. When the run function
1549 * returns this function also returns and passes control back to the main
1550 * program. The return value can be used to determine whether there are any
1551 * active run functions left. This function does nothing if there are no active
1552 * registered run functions.
1553 *
1554 * @param ctx the plug-in context containing the plug-ins
1555 * @return whether there are active run functions waiting to be run
1556 */
1558
1559/**
1560 * Sets startup arguments for the specified plug-in context. Like for usual
1561 * C main functions, the first argument is expected to be the name of the
1562 * program being executed or an empty string and the argument array should be
1563 * terminated by NULL entry. If the main program is
1564 * about to pass startup arguments to plug-ins it should call this function
1565 * before starting any plug-ins in the context. The arguments are not copied
1566 * and the caller is responsible for keeping the argument data available once
1567 * the arguments have been set until the context is destroyed. Plug-ins can
1568 * access the startup arguments using ::cp_get_context_args.
1569 *
1570 * @param ctx the plug-in context
1571 * @param argv a NULL-terminated array of arguments
1572 */
1574
1575/**
1576 * Returns the startup arguments associated with the specified
1577 * plug-in context. This function is intended to be used by a plug-in runtime.
1578 * Startup arguments are set by the main program using ::cp_set_context_args.
1579 * The returned argument count is zero and the array pointer is NULL if no
1580 * arguments have been set.
1581 *
1582 * @param ctx the plug-in context
1583 * @param argc a pointer to a location where the number of startup arguments is stored, or NULL for none
1584 * @return an argument array terminated by NULL or NULL if not set
1585 */
1587
1588/*@}*/
1589
1590
1591/**
1592 * @defgroup cFuncsSymbols Dynamic symbols
1593 * @ingroup cFuncs
1594 *
1595 * These functions can be used to dynamically access symbols exported by the
1596 * plug-ins. They are intended to be used by a plug-in runtime or by the main
1597 * program.
1598 */
1599/*@{*/
1600
1601/**
1602 * Defines a context specific symbol. If a plug-in has symbols which have
1603 * a plug-in instance specific value then the plug-in should define those
1604 * symbols when it is started. The defined symbols are cleared
1605 * automatically when the plug-in instance is stopped. Symbols can not be
1606 * redefined.
1607 *
1608 * @param ctx the plug-in context
1609 * @param name the name of the symbol
1610 * @param ptr pointer value for the symbol
1611 * @return @ref CP_OK (zero) on success or a status code on failure
1612 */
1613CP_C_API cp_status_t cp_define_symbol(cp_context_t *ctx, const char *name, void *ptr) CP_GCC_NONNULL(1, 2, 3);
1614
1615/**
1616 * Resolves a symbol provided by the specified plug-in. The plug-in is started
1617 * automatically if it is not already active. The symbol may be context
1618 * specific or global. The framework first looks for a context specific
1619 * symbol and then falls back to resolving a global symbol exported by the
1620 * plug-in runtime library. The symbol can be released using
1621 * ::cp_release_symbol when it is not needed anymore. Pointers obtained from
1622 * this function must not be passed on to other plug-ins or the main
1623 * program.
1624 *
1625 * When a plug-in runtime calls this function the plug-in framework creates
1626 * a dynamic dependency from the symbol using plug-in to the symbol
1627 * defining plug-in. The symbol using plug-in is stopped automatically if the
1628 * symbol defining plug-in is about to be stopped. If the symbol using plug-in
1629 * does not explicitly release the symbol then it is automatically released
1630 * after a call to the stop function. It is not safe to refer to a dynamically
1631 * resolved symbol in the stop function except to release it using
1632 * ::cp_release_symbol.
1633 *
1634 * When the main program calls this function it is the responsibility of the
1635 * main program to always release the symbol before the symbol defining plug-in
1636 * is stopped. It is a fatal error if the symbol is not released before the
1637 * symbol defining plug-in is stopped.
1638 *
1639 * @param ctx the plug-in context
1640 * @param id the identifier of the symbol defining plug-in
1641 * @param name the name of the symbol
1642 * @param status a pointer to the location where the status code is to be stored, or NULL
1643 * @return the pointer associated with the symbol or NULL on failure
1644 */
1645CP_C_API void *cp_resolve_symbol(cp_context_t *ctx, const char *id, const char *name, cp_status_t *status) CP_GCC_NONNULL(1, 2, 3);
1646
1647/**
1648 * Releases a previously obtained symbol. The pointer must not be used after
1649 * the symbol has been released. The symbol is released
1650 * only after as many calls to this function as there have been for
1651 * ::cp_resolve_symbol for the same plug-in and symbol.
1652 *
1653 * @param ctx the plug-in context
1654 * @param ptr the pointer associated with the symbol
1655 */
1656CP_C_API void cp_release_symbol(cp_context_t *ctx, const void *ptr) CP_GCC_NONNULL(1, 2);
1657
1658/*@}*/
1659
1660
1661/**
1662 * @defgroup cFuncsLoaders Plug-in loaders
1663 * @ingroup cFuncs
1664 *
1665 * These functions are used to construct standard plug-in loaders. Currently
1666 * there is a single plug-in loader for loading plug-ins from local plug-in
1667 * collections.
1668 */
1669/*@{*/
1670
1671/**
1672 * Creates and returns a new instance of a local plug-in loader. The resources
1673 * used by the returned instance can be released by calling
1674 * ::cp_destroy_local_ploader when the loader is not needed anymore.
1675 * Remaining local plug-in loaders are automatically destroyed when the
1676 * plug-in framework is destroyed. The created plug-in loader can be
1677 * registered with a plug-in context using ::cp_register_ploader.
1678 *
1679 * @param status pointer to the location where status code is to be stored, or NULL
1680 * @return the new plug-in loader instance, or NULL on failure
1681 */
1683
1684/**
1685 * Releases the resources allocated by a previously created local plug-in
1686 * loader. The specified loader must have been obtained by a call to
1687 * ::cp_create_local_ploader. The loader to be destroyed must not be
1688 * registered with any plug-in context.
1689 *
1690 * @param the plug-in loader to be destroyed
1691 */
1693
1694/**
1695 * Registers a new directory to be scanned by the specified local
1696 * plug-in loader. Returns @ref CP_OK if the directory has already been
1697 * registered.
1698 *
1699 * @param loader the plug-in loader obtained from ::cp_create_local_ploader
1700 * @param dir the directory to register
1701 * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if insufficient memory
1702 */
1704
1705/**
1706 * Unregisters a directory from the specified local plug-in loader. Does
1707 * nothing if the specified directory has not been registered. This does not
1708 * affect the status of already loaded plug-ins.
1709 *
1710 * @param loader the plug-in loader obtained from ::cp_create_local_ploader
1711 * @param dir the directory to unregister
1712 */
1714
1715/**
1716 * Unregisters all registered directories from the specified local plug-in
1717 * loader. This does not affect the status of already loaded plug-ins.
1718 *
1719 * @param loader the plug-in
1720 */
1722
1723/*@}*/
1724
1725
1726#ifdef __cplusplus
1727}
1728#endif /*__cplusplus*/
1729
1730#endif /*CPLUFF_H_*/
CP_IMPORT cp_status_t cp_register_ploader(cp_context_t *ctx, cp_plugin_loader_t *loader)
Registers a plug-in loader that will be used to load plug-ins into this context when cp_scan_plugins ...
CP_IMPORT cp_plugin_state_t cp_get_plugin_state(cp_context_t *ctx, const char *id)
Returns the current state of the specified plug-in.
CP_IMPORT void cp_destroy_context(cp_context_t *ctx)
Destroys the specified plug-in context and releases the associated resources.
CP_IMPORT void cp_lpl_unregister_dir(cp_plugin_loader_t *loader, const char *dir)
Unregisters a directory from the specified local plug-in loader.
CP_IMPORT void cp_release_symbol(cp_context_t *ctx, const void *ptr)
Releases a previously obtained symbol.
CP_IMPORT void cp_unregister_ploaders(cp_context_t *ctx)
Unregisters all registered plug-in loaders from a plug-in context.
void(* cp_plugin_listener_func_t)(const char *plugin_id, cp_plugin_state_t old_state, cp_plugin_state_t new_state, void *user_data)
A listener function called synchronously after a plugin state change.
Definition cpluff.h:347
CP_IMPORT cp_ext_point_t ** cp_get_ext_points_info(cp_context_t *ctx, cp_status_t *status, int *num)
Returns static information about the currently installed extension points.
CP_IMPORT cp_status_t cp_init(void)
Initializes the plug-in framework.
CP_IMPORT cp_context_t * cp_create_context(cp_status_t *status)
Creates a new plug-in context which can be used as a container for plug-ins.
CP_IMPORT void cp_set_plugin_descriptor_name(cp_context_t *ctx, const char *name)
Changes the file name in the plug-in the plug-in descriptor is loaded from.
CP_IMPORT cp_plugin_info_t ** cp_get_plugins_info(cp_context_t *ctx, cp_status_t *status, int *num)
Returns static information about the installed plug-ins.
void(* cp_logger_func_t)(cp_log_severity_t severity, const char *msg, const char *apid, void *user_data)
A logger function called to log selected plug-in framework messages.
Definition cpluff.h:361
CP_IMPORT cp_status_t cp_start_plugin(cp_context_t *ctx, const char *id)
Starts a plug-in.
CP_IMPORT cp_status_t cp_run_function(cp_context_t *ctx, cp_run_func_t runfunc)
Registers a new run function.
CP_IMPORT char * cp_lookup_cfg_value(cp_cfg_element_t *base, const char *path)
Traverses a configuration element tree and returns the value of the specified element or attribute.
CP_IMPORT int cp_is_logged(cp_context_t *ctx, cp_log_severity_t severity)
Returns whether a message of the specified severity would get logged.
CP_IMPORT cp_status_t cp_stop_plugin(cp_context_t *ctx, const char *id)
Stops a plug-in.
CP_IMPORT cp_status_t cp_register_logger(cp_context_t *ctx, cp_logger_func_t logger, void *user_data, cp_log_severity_t min_severity)
Registers a logger with a plug-in context or updates the settings of a registered logger.
CP_IMPORT void cp_set_fatal_error_handler(cp_fatal_error_func_t error_handler)
Sets the fatal error handler called on non-recoverable errors.
CP_IMPORT void cp_set_context_args(cp_context_t *ctx, char **argv)
Sets startup arguments for the specified plug-in context.
CP_IMPORT cp_status_t cp_register_pcollection(cp_context_t *ctx, const char *dir)
Registers a local plug-in collection with a plug-in context.
CP_IMPORT cp_plugin_info_t * cp_load_plugin_descriptor(cp_context_t *ctx, const char *path, cp_status_t *status)
Loads a plug-in descriptor from the specified plug-in installation path and returns information about...
CP_IMPORT int cp_run_plugins_step(cp_context_t *ctx)
Runs one registered run function.
CP_IMPORT const char * cp_get_version(void)
Returns the release version string of the linked in C-Pluff implementation.
CP_IMPORT void cp_release_info(cp_context_t *ctx, void *info)
Releases a previously obtained reference counted information object.
CP_IMPORT void cp_unregister_ploader(cp_context_t *ctx, cp_plugin_loader_t *loader)
Unregisters a previously registered plug-in loader from a plug-in context.
CP_IMPORT cp_status_t cp_install_plugin(cp_context_t *ctx, cp_plugin_info_t *pi)
Installs the plug-in described by the specified plug-in information structure to the specified plug-i...
CP_IMPORT void * cp_resolve_symbol(cp_context_t *ctx, const char *id, const char *name, cp_status_t *status)
Resolves a symbol provided by the specified plug-in.
CP_IMPORT void cp_unregister_logger(cp_context_t *ctx, cp_logger_func_t logger)
Removes a logger registration.
void(* cp_fatal_error_func_t)(const char *msg)
A fatal error handler for handling unrecoverable errors.
Definition cpluff.h:372
CP_IMPORT cp_status_t cp_define_symbol(cp_context_t *ctx, const char *name, void *ptr)
Defines a context specific symbol.
int(* cp_run_func_t)(void *plugin_data)
A run function registered by a plug-in to perform work.
Definition cpluff.h:384
CP_IMPORT const char * cp_get_host_type(void)
Returns the canonical host type associated with the linked in C-Pluff implementation.
CP_IMPORT cp_status_t cp_register_plistener(cp_context_t *ctx, cp_plugin_listener_func_t listener, void *user_data)
Registers a plug-in listener with a plug-in context.
CP_IMPORT cp_plugin_info_t * cp_get_plugin_info(cp_context_t *ctx, const char *id, cp_status_t *status)
Returns static information about the specified plug-in.
CP_IMPORT cp_cfg_element_t * cp_lookup_cfg_element(cp_cfg_element_t *base, const char *path)
Traverses a configuration element tree and returns the specified element.
CP_IMPORT void cp_set_plugin_descriptor_root_element(cp_context_t *ctx, const char *root)
Changes the XML root element's name in plug-in descriptor.
CP_IMPORT cp_plugin_loader_t * cp_create_local_ploader(cp_status_t *status)
Creates and returns a new instance of a local plug-in loader.
CP_IMPORT cp_status_t cp_lpl_register_dir(cp_plugin_loader_t *loader, const char *dir)
Registers a new directory to be scanned by the specified local plug-in loader.
CP_IMPORT char ** cp_get_context_args(cp_context_t *ctx, int *argc)
Returns the startup arguments associated with the specified plug-in context.
CP_IMPORT void cp_unregister_plistener(cp_context_t *ctx, cp_plugin_listener_func_t listener)
Removes a plug-in listener from a plug-in context.
CP_IMPORT cp_plugin_info_t * cp_load_plugin_descriptor_from_memory(cp_context_t *ctx, const char *buffer, unsigned int buffer_len, cp_status_t *status)
Loads a plug-in descriptor from the specified block of memory and returns information about the plug-...
CP_IMPORT void cp_unregister_pcollection(cp_context_t *ctx, const char *dir)
Unregisters a previously registered plug-in collection from a plug-in context.
CP_IMPORT void cp_unregister_pcollections(cp_context_t *ctx)
Unregisters all plug-in collections from a plug-in context.
CP_IMPORT void cp_lpl_unregister_dirs(cp_plugin_loader_t *loader)
Unregisters all registered directories from the specified local plug-in loader.
struct cp_context_t cp_context_t
A plug-in context represents the co-operation environment of a set of plug-ins from the perspective o...
Definition cpluff.h:281
CP_IMPORT void cp_stop_plugins(cp_context_t *ctx)
Stops all active plug-ins.
CP_IMPORT void cp_destroy(void)
Destroys the plug-in framework and releases the resources used by it.
CP_IMPORT cp_status_t cp_scan_plugins(cp_context_t *ctx, int flags)
Scans for plug-ins in the registered plug-in directories, installing new plug-ins and upgrading insta...
CP_IMPORT void cp_run_plugins(cp_context_t *ctx)
Runs the started plug-ins as long as there is something to run.
CP_IMPORT void cp_uninstall_plugins(cp_context_t *ctx)
Uninstalls all plug-ins.
CP_IMPORT void cp_destroy_local_ploader(cp_plugin_loader_t *loader)
Releases the resources allocated by a previously created local plug-in loader.
CP_IMPORT cp_status_t cp_uninstall_plugin(cp_context_t *ctx, const char *id)
Uninstalls the specified plug-in.
CP_IMPORT cp_extension_t ** cp_get_extensions_info(cp_context_t *ctx, const char *extpt_id, cp_status_t *status, int *num)
Returns static information about the currently installed extension points.
CP_IMPORT void cp_log(cp_context_t *ctx, cp_log_severity_t severity, const char *msg)
Emits a new log message.
Common defines shared by C-Pluff C and C++ APIs.
#define CP_GCC_PURE
Declares a function as pure function having no side effects.
Definition cpluffdef.h:190
#define CP_GCC_NONNULL(...)
Specifies that some pointer arguments to a function should have non-NULL values.
Definition cpluffdef.h:195
#define CP_C_API
Marks a symbol declaration to be part of the C-Pluff C API.
Definition cpluff.h:61
cp_log_severity_t
An enumeration of possible message severities for framework logging.
Definition cpluff.h:241
cp_plugin_state_t
An enumeration of possible plug-in states.
Definition cpluff.h:175
cp_status_t
An enumeration of status codes returned by API functions.
Definition cpluff.h:133
@ CP_LOG_DEBUG
Used for detailed debug messages.
Definition cpluff.h:244
@ CP_LOG_WARNING
Used for messages warning about possible problems.
Definition cpluff.h:250
@ CP_LOG_INFO
Used for informational messages such as plug-in state changes.
Definition cpluff.h:247
@ CP_LOG_ERROR
Used for messages reporting errors.
Definition cpluff.h:253
@ CP_PLUGIN_INSTALLED
Plug-in is installed.
Definition cpluff.h:190
@ CP_PLUGIN_STARTING
Plug-in is starting.
Definition cpluff.h:213
@ CP_PLUGIN_STOPPING
Plug-in is stopping.
Definition cpluff.h:224
@ CP_PLUGIN_RESOLVED
Plug-in dependencies have been resolved.
Definition cpluff.h:202
@ CP_PLUGIN_UNINSTALLED
Plug-in is not installed.
Definition cpluff.h:181
@ CP_PLUGIN_ACTIVE
Plug-in has been successfully started and it has not yet been stopped.
Definition cpluff.h:230
@ CP_ERR_DEPENDENCY
Plug-in dependencies could not be satisfied.
Definition cpluff.h:157
@ CP_ERR_IO
An I/O error occurred.
Definition cpluff.h:148
@ CP_OK
Operation was performed successfully (equals to zero).
Definition cpluff.h:139
@ CP_ERR_UNKNOWN
The specified object is unknown to the framework.
Definition cpluff.h:145
@ CP_ERR_CONFLICT
Plug-in or symbol conflicts with another plug-in or symbol.
Definition cpluff.h:154
@ CP_ERR_RESOURCE
Not enough memory or other operating system resources available.
Definition cpluff.h:142
@ CP_ERR_MALFORMED
Malformed plug-in descriptor was encountered when loading a plug-in.
Definition cpluff.h:151
@ CP_ERR_RUNTIME
Plug-in runtime signaled an error.
Definition cpluff.h:160
A configuration element contains configuration information for an extension.
Definition cpluff.h:670
cp_cfg_element_t * children
An array of num_children childrens of this element.
Definition cpluff.h:707
char * value
An optional value of this configuration element.
Definition cpluff.h:692
unsigned int index
The index of this element among its siblings (0-based).
Definition cpluff.h:698
char * name
The name of the configuration element.
Definition cpluff.h:676
char ** atts
An array of pointers to alternating attribute names and values.
Definition cpluff.h:685
cp_cfg_element_t * parent
A pointer to the parent element or NULL if this is a root element.
Definition cpluff.h:695
unsigned int num_atts
Number of attribute name, value pairs in the atts array.
Definition cpluff.h:679
unsigned int num_children
Number of children in the children array.
Definition cpluff.h:701
Extension point structure captures information about an extension point.
Definition cpluff.h:569
char * schema_path
An optional path to the extension schema definition.
Definition cpluff.h:606
char * name
An optional extension point name.
Definition cpluff.h:598
cp_plugin_info_t * plugin
A pointer to plug-in information containing this extension point.
Definition cpluff.h:576
char * identifier
The unique identifier of the extension point.
Definition cpluff.h:590
Extension structure captures information about an extension.
Definition cpluff.h:614
char * name
An optional extension name.
Definition cpluff.h:650
char * ext_point_id
The unique identifier of the extension point this extension is attached to.
Definition cpluff.h:628
cp_cfg_element_t * configuration
Extension configuration starting with the extension element.
Definition cpluff.h:658
cp_plugin_info_t * plugin
A pointer to plug-in information containing this extension.
Definition cpluff.h:621
char * local_id
An optional local identifier uniquely identifying the extension within the host plug-in.
Definition cpluff.h:635
char * identifier
An optional unique identifier of the extension.
Definition cpluff.h:642
Information about plug-in import.
Definition cpluff.h:533
char * plugin_id
The identifier of the imported plug-in.
Definition cpluff.h:539
char * version
An optional version requirement.
Definition cpluff.h:549
int optional
Is this import optional.
Definition cpluff.h:560
Plug-in information structure captures information about a plug-in.
Definition cpluff.h:399
cp_extension_t * extensions
An array of num_extensions extensions provided by this plug-in.
Definition cpluff.h:524
char * runtime_funcs_symbol
The symbol pointing to the plug-in runtime function information or NULL if none.
Definition cpluff.h:504
char * version
An optional release version string.
Definition cpluff.h:423
unsigned int num_extensions
Number of extensions in extensions array.
Definition cpluff.h:517
char * name
An optional plug-in name.
Definition cpluff.h:416
char * abi_bw_compatibility
Optional ABI compatibility information.
Definition cpluff.h:454
cp_ext_point_t * ext_points
An array of num_ext_points extension points provided by this plug-in.
Definition cpluff.h:514
unsigned int num_ext_points
Number of extension points in ext_points array.
Definition cpluff.h:507
char * req_cpluff_version
Optional C-Pluff version requirement.
Definition cpluff.h:478
char * provider_name
An optional provider name.
Definition cpluff.h:432
char * api_bw_compatibility
Optional API compatibility information.
Definition cpluff.h:468
unsigned int num_imports
Number of import entries in the imports array.
Definition cpluff.h:481
char * plugin_path
Path of the plugin directory or NULL if not known.
Definition cpluff.h:441
cp_plugin_import_t * imports
An array of num_imports import entries.
Definition cpluff.h:487
char * runtime_lib_name
The base name of the plug-in runtime library, or NULL if none.
Definition cpluff.h:496
char * identifier
The obligatory unique identifier of the plugin.
Definition cpluff.h:408
A plug-in loader instance.
Definition cpluff.h:839
void(* release_plugins)(void *data, cp_context_t *ctx, cp_plugin_info_t **plugins)
A function called to release plug-in information returned by the scan_plugins function.
Definition cpluff.h:900
void * data
An opaque data pointer for this plug-in loader instance.
Definition cpluff.h:847
int(* resolve_files)(void *data, cp_context_t *ctx, cp_plugin_info_t *plugin)
A function called to ensure that the plug-in runtime code and data is locally available.
Definition cpluff.h:886
Container for plug-in runtime information.
Definition cpluff.h:737
void(* stop)(void *data)
A stop function called to stop a plugin instance.
Definition cpluff.h:803
void(* destroy)(void *data)
A destroy function called to destroy a plug-in instance.
Definition cpluff.h:817
int(* start)(void *data)
A start function called to start a plug-in instance.
Definition cpluff.h:778

Generated on Thu Mar 14 2024 19:33:41 for C-Pluff C API by doxygen 1.9.8