C-Pluff C API  0.1.4
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
44 extern "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 
162 };
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 
232 };
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 
255 };
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  */
281 typedef struct cp_context_t cp_context_t;
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_status_t enumeration. */
312 
313 /** A type for cp_plugin_state_t enumeration. */
315 
316 /** A type for cp_log_severity_t enumeration. */
318 
319 /*@}*/
320 
321 /**
322  * @defgroup cTypedefsFuncs Callback function types
323  * @ingroup cTypedefs
324  * Typedefs for client supplied callback functions.
325  */
326 /*@{*/
327 
328 /**
329  * A listener function called synchronously after a plugin state change.
330  * The function should return promptly.
331  * @ref cFuncsInit "Library initialization",
332  * @ref cFuncsContext "plug-in context management",
333  * @ref cFuncsPlugin "plug-in management",
334  * listener registration (::cp_register_plistener and ::cp_unregister_plistener)
335  * and @ref cFuncsSymbols "dynamic symbol" functions must not be called from
336  * within a plug-in listener invocation. Listener functions are registered
337  * using ::cp_register_plistener.
338  *
339  * @param plugin_id the plug-in identifier
340  * @param old_state the old plug-in state
341  * @param new_state the new plug-in state
342  * @param user_data the user data pointer supplied at listener registration
343  */
344 typedef 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);
345 
346 /**
347  * A logger function called to log selected plug-in framework messages. The
348  * messages may be localized. Plug-in framework API functions must not
349  * be called from within a logger function invocation. In a multi-threaded
350  * environment logger function invocations are serialized by the framework.
351  * Logger functions are registered using ::cp_register_logger.
352  *
353  * @param severity the severity of the message
354  * @param msg the message to be logged, possibly localized
355  * @param apid the identifier of the activating plug-in or NULL for the main program
356  * @param user_data the user data pointer given when the logger was registered
357  */
358 typedef void (*cp_logger_func_t)(cp_log_severity_t severity, const char *msg, const char *apid, void *user_data);
359 
360 /**
361  * A fatal error handler for handling unrecoverable errors. If the error
362  * handler returns then the framework aborts the program. Plug-in framework
363  * API functions must not be called from within a fatal error handler
364  * invocation. The fatal error handler function is set using
365  * ::cp_set_fatal_error_handler.
366  *
367  * @param msg the possibly localized error message
368  */
369 typedef void (*cp_fatal_error_func_t)(const char *msg);
370 
371 /**
372  * A run function registered by a plug-in to perform work.
373  * The run function should perform a finite chunk of work and it should
374  * return a non-zero value if there is more work to be done. Run functions
375  * are registered using ::cp_run_function and the usage is discussed in
376  * more detail in the @ref cFuncsPluginExec "serial execution" section.
377  *
378  * @param plugin_data the plug-in instance data pointer
379  * @return non-zero if there is more work to be done or zero if finished
380  */
381 typedef int (*cp_run_func_t)(void *plugin_data);
382 
383 /*@}*/
384 
385 
386 /* Data structures */
387 
388 /**
389  * @ingroup cStructs
390  * Plug-in information structure captures information about a plug-in. This
391  * information can be loaded from a plug-in descriptor using
392  * ::cp_load_plugin_descriptor. Information about installed plug-ins can
393  * be obtained using ::cp_get_plugin_info and ::cp_get_plugins_info. This
394  * structure corresponds to the @a plugin element in a plug-in descriptor.
395  */
397 
398  /**
399  * The obligatory unique identifier of the plugin. A recommended way
400  * to generate identifiers is to use domain name service (DNS) prefixes
401  * (for example, org.cpluff.ExamplePlugin) to avoid naming conflicts. This
402  * corresponds to the @a id attribute of the @a plugin element in a plug-in
403  * descriptor.
404  */
405  char *identifier;
406 
407  /**
408  * An optional plug-in name. NULL if not available. The plug-in name is
409  * intended only for display purposes and the value can be localized.
410  * This corresponds to the @a name attribute of the @a plugin element in
411  * a plug-in descriptor.
412  */
413  char *name;
414 
415  /**
416  * An optional release version string. NULL if not available. This
417  * corresponds to the @a version attribute of the @a plugin element in
418  * a plug-in descriptor.
419  */
420  char *version;
421 
422  /**
423  * An optional provider name. NULL if not available. This is the name of
424  * the author or the organization providing the plug-in. The
425  * provider name is intended only for display purposes and the value can
426  * be localized. This corresponds to the @a provider-name attribute of the
427  * @a plugin element in a plug-in descriptor.
428  */
430 
431  /**
432  * Path of the plugin directory or NULL if not known. This is the
433  * (absolute or relative) path to the plug-in directory containing
434  * plug-in data and the plug-in runtime library. The value corresponds
435  * to the path specified to ::cp_load_plugin_descriptor when loading
436  * the plug-in.
437  */
438  char *plugin_path;
439 
440  /**
441  * Optional ABI compatibility information. NULL if not available.
442  * This is the earliest version of the plug-in interface the current
443  * interface is backwards compatible with when it comes to the application
444  * binary interface (ABI) of the plug-in. That is, plug-in clients compiled against
445  * any plug-in interface version from @a abi_bw_compatibility to
446  * @ref version (inclusive) can use the current version of the plug-in
447  * binary. This describes binary or runtime compatibility.
448  * The value corresponds to the @a abi-compatibility
449  * attribute of the @a backwards-compatibility element in a plug-in descriptor.
450  */
452 
453  /**
454  * Optional API compatibility information. NULL if not available.
455  * This is the earliest version of the plug-in interface the current
456  * interface is backwards compatible with when it comes to the
457  * application programming interface (API) of the plug-in. That is,
458  * plug-in clients written for any plug-in interface version from
459  * @a api_bw_compatibility to @ref version (inclusive) can be compiled
460  * against the current version of the plug-in API. This describes
461  * source or build time compatibility. The value corresponds to the
462  * @a api-compatibility attribute of the @a backwards-compatibility
463  * element in a plug-in descriptor.
464  */
466 
467  /**
468  * Optional C-Pluff version requirement. NULL if not available.
469  * This is the version of the C-Pluff implementation the plug-in was
470  * compiled against. It is used to determine the compatibility of
471  * the plug-in runtime and the linked in C-Pluff implementation. Any
472  * C-Pluff version that is backwards compatible on binary level with the
473  * specified version fulfills the requirement.
474  */
476 
477  /** Number of import entries in the @ref imports array. */
478  unsigned int num_imports;
479 
480  /**
481  * An array of @ref num_imports import entries. These correspond to
482  * @a import elements in a plug-in descriptor.
483  */
485 
486  /**
487  * The base name of the plug-in runtime library, or NULL if none.
488  * A platform specific prefix (for example, "lib") and an extension
489  * (for example, ".dll" or ".so") may be added to the base name.
490  * This corresponds to the @a library attribute of the
491  * @a runtime element in a plug-in descriptor.
492  */
494 
495  /**
496  * The symbol pointing to the plug-in runtime function information or
497  * NULL if none. The symbol with this name should point to an instance of
498  * @ref cp_plugin_runtime_t structure. This corresponds to the
499  * @a funcs attribute of the @a runtime element in a plug-in descriptor.
500  */
502 
503  /** Number of extension points in @ref ext_points array. */
504  unsigned int num_ext_points;
505 
506  /**
507  * An array of @ref num_ext_points extension points provided by this
508  * plug-in. These correspond to @a extension-point elements in a
509  * plug-in descriptor.
510  */
512 
513  /** Number of extensions in @ref extensions array. */
514  unsigned int num_extensions;
515 
516  /**
517  * An array of @ref num_extensions extensions provided by this
518  * plug-in. These correspond to @a extension elements in a plug-in
519  * descriptor.
520  */
522 
523 };
524 
525 /**
526  * @ingroup cStructs
527  * Information about plug-in import. Plug-in import structures are
528  * contained in @ref cp_plugin_info_t::imports.
529  */
531 
532  /**
533  * The identifier of the imported plug-in. This corresponds to the
534  * @a plugin attribute of the @a import element in a plug-in descriptor.
535  */
536  char *plugin_id;
537 
538  /**
539  * An optional version requirement. NULL if no version requirement.
540  * This is the version of the imported plug-in the importing plug-in was
541  * compiled against. Any version of the imported plug-in that is
542  * backwards compatible with this version fulfills the requirement.
543  * This corresponds to the @a if-version attribute of the @a import
544  * element in a plug-in descriptor.
545  */
546  char *version;
547 
548  /**
549  * Is this import optional. 1 for optional and 0 for mandatory import.
550  * An optional import causes the imported plug-in to be started if it is
551  * available but does not stop the importing plug-in from starting if the
552  * imported plug-in is not available. If the imported plug-in is available
553  * but the API version conflicts with the API version requirement then the
554  * importing plug-in fails to start. This corresponds to the @a optional
555  * attribute of the @a import element in a plug-in descriptor.
556  */
557  int optional;
558 };
559 
560 /**
561  * @ingroup cStructs
562  * Extension point structure captures information about an extension
563  * point. Extension point structures are contained in
564  * @ref cp_plugin_info_t::ext_points.
565  */
567 
568  /**
569  * A pointer to plug-in information containing this extension point.
570  * This reverse pointer is provided to make it easy to get information
571  * about the plug-in which is hosting a particular extension point.
572  */
574 
575  /**
576  * The local identifier uniquely identifying the extension point within the
577  * host plug-in. This corresponds to the @name id attribute of an
578  * @a extension-point element in a plug-in descriptor.
579  */
580  char *local_id;
581 
582  /**
583  * The unique identifier of the extension point. This is automatically
584  * constructed by concatenating the identifier of the host plug-in and
585  * the local identifier of the extension point.
586  */
587  char *identifier;
588 
589  /**
590  * An optional extension point name. NULL if not available. The extension
591  * point name is intended for display purposes only and the value can be
592  * localized. This corresponds to the @a name attribute of
593  * an @a extension-point element in a plug-in descriptor.
594  */
595  char *name;
596 
597  /**
598  * An optional path to the extension schema definition.
599  * NULL if not available. The path is relative to the plug-in directory.
600  * This corresponds to the @a schema attribute
601  * of an @a extension-point element in a plug-in descriptor.
602  */
603  char *schema_path;
604 };
605 
606 /**
607  * @ingroup cStructs
608  * Extension structure captures information about an extension. Extension
609  * structures are contained in @ref cp_plugin_info_t::extensions.
610  */
612 
613  /**
614  * A pointer to plug-in information containing this extension.
615  * This reverse pointer is provided to make it easy to get information
616  * about the plug-in which is hosting a particular extension.
617  */
619 
620  /**
621  * The unique identifier of the extension point this extension is
622  * attached to. This corresponds to the @a point attribute of an
623  * @a extension element in a plug-in descriptor.
624  */
626 
627  /**
628  * An optional local identifier uniquely identifying the extension within
629  * the host plug-in. NULL if not available. This corresponds to the
630  * @a id attribute of an @a extension element in a plug-in descriptor.
631  */
632  char *local_id;
633 
634  /**
635  * An optional unique identifier of the extension. NULL if not available.
636  * This is automatically constructed by concatenating the identifier
637  * of the host plug-in and the local identifier of the extension.
638  */
639  char *identifier;
640 
641  /**
642  * An optional extension name. NULL if not available. The extension name
643  * is intended for display purposes only and the value can be localized.
644  * This corresponds to the @a name attribute
645  * of an @a extension element in a plug-in descriptor.
646  **/
647  char *name;
648 
649  /**
650  * Extension configuration starting with the extension element.
651  * This includes extension configuration information as a tree of
652  * configuration elements. These correspond to the @a extension
653  * element and its contents in a plug-in descriptor.
654  */
656 };
657 
658 /**
659  * @ingroup cStructs
660  * A configuration element contains configuration information for an
661  * extension. Utility functions ::cp_lookup_cfg_element and
662  * ::cp_lookup_cfg_value can be used for traversing the tree of
663  * configuration elements. Pointer to the root configuration element is
664  * stored at @ref cp_extension_t::configuration and others are contained as
665  * @ref cp_cfg_element_t::children "children" of parent elements.
666  */
668 
669  /**
670  * The name of the configuration element. This corresponds to the name of
671  * the element in a plug-in descriptor.
672  */
673  char *name;
674 
675  /** Number of attribute name, value pairs in the @ref atts array. */
676  unsigned int num_atts;
677 
678  /**
679  * An array of pointers to alternating attribute names and values.
680  * Attribute values can be localized.
681  */
682  char **atts;
683 
684  /**
685  * An optional value of this configuration element. NULL if not available.
686  * The value can be localized. This corresponds to the
687  * text contents of the element in a plug-in descriptor.
688  */
689  char *value;
690 
691  /** A pointer to the parent element or NULL if this is a root element. */
693 
694  /** The index of this element among its siblings (0-based). */
695  unsigned int index;
696 
697  /** Number of children in the @ref children array. */
698  unsigned int num_children;
699 
700  /**
701  * An array of @ref num_children childrens of this element. These
702  * correspond to child elements in a plug-in descriptor.
703  */
705 };
706 
707 /**
708  * @ingroup cStructs
709  * Container for plug-in runtime information. A plug-in runtime defines a
710  * static instance of this structure to pass information to the plug-in
711  * framework. The plug-in framework then uses the information
712  * to create and control plug-in instances. The symbol pointing
713  * to the runtime information instance is named by the @a funcs
714  * attribute of the @a runtime element in a plug-in descriptor.
715  *
716  * The following graph displays how these functions are used to control the
717  * state of the plug-in instance.
718  *
719  * @dot
720  * digraph lifecycle {
721  * rankdir=LR;
722  * node [shape=ellipse, fontname=Helvetica, fontsize=10];
723  * edge [fontname=Helvetica, fontsize=10];
724  * none [label="no instance"];
725  * inactive [label="inactive"];
726  * active [label="active"];
727  * none -> inactive [label="create", URL="\ref create"];
728  * inactive -> active [label="start", URL="\ref start"];
729  * active -> inactive [label="stop", URL="\ref stop"];
730  * inactive -> none [label="destroy", URL="\ref destroy"];
731  * }
732  * @enddot
733  */
735 
736  /**
737  * An initialization function called to create a new plug-in
738  * runtime instance. The initialization function initializes and
739  * returns an opaque plug-in instance data pointer which is then
740  * passed on to other control functions. This data pointer should
741  * be used to access plug-in instance specific data. For example,
742  * the context reference must be stored as part of plug-in instance
743  * data if the plug-in runtime needs it. On failure, the function
744  * must return NULL.
745  *
746  * C-pluff API functions must not be called from within a create
747  * function invocation and symbols from imported plug-ins must not be
748  * used because they may not available yet.
749  *
750  * @param ctx the plug-in context of the new plug-in instance
751  * @return an opaque pointer to plug-in instance data or NULL on failure
752  */
753  void *(*create)(cp_context_t *ctx);
754 
755  /**
756  * A start function called to start a plug-in instance.
757  * The start function must return zero (CP_OK) on success and non-zero
758  * on failure. If the start fails then the stop function (if any) is
759  * called to clean up plug-in state. @ref cFuncsInit "Library initialization",
760  * @ref cFuncsContext "plug-in context management" and
761  * @ref cFuncsPlugin "plug-in management" functions must not be
762  * called from within a start function invocation. The start function
763  * pointer can be NULL if the plug-in runtime does not have a start
764  * function.
765  *
766  * The start function implementation should set up plug-in and return
767  * promptly. If there is further work to be done then a plug-in can
768  * start a thread or register a run function using ::cp_run_function.
769  * Symbols from imported plug-ins are guaranteed to be available for
770  * the start function.
771  *
772  * @param data an opaque pointer to plug-in instance data
773  * @return non-zero on success, or zero on failure
774  */
775  int (*start)(void *data);
776 
777  /**
778  * A stop function called to stop a plugin instance.
779  * This function must cease all plug-in runtime activities.
780  * @ref cFuncsInit "Library initialization",
781  * @ref cFuncsContext "plug-in context management",
782  * @ref cFuncsPlugin "plug-in management"
783  * functions, ::cp_run_function and ::cp_resolve_symbol must not be called
784  * from within a stop function invocation. The stop function pointer can
785  * be NULL if the plug-in runtime does not have a stop function.
786  * It is guaranteed that no run functions registered by the plug-in are
787  * called simultaneously or after the call to the stop function.
788  *
789  * The stop function should release any external resources hold by
790  * the plug-in. Dynamically resolved symbols are automatically released
791  * and dynamically defined symbols and registered run functions are
792  * automatically unregistered after the call to stop function.
793  * Resolved external symbols are still available for the stop function
794  * and symbols provided by the plug-in should remain available
795  * after the call to stop function (although functionality might be
796  * limited). Final cleanup can be safely done in the destroy function.
797  *
798  * @param data an opaque pointer to plug-in instance data
799  */
800  void (*stop)(void *data);
801 
802  /**
803  * A destroy function called to destroy a plug-in instance.
804  * This function should release any plug-in instance data.
805  * The plug-in is stopped before this function is called.
806  * C-Pluff API functions must not be called from within a destroy
807  * function invocation and symbols from imported plug-ins must not be
808  * used because they may not be available anymore. Correspondingly,
809  * it is guaranteed that the symbols provided by the plug-in are not
810  * used by other plug-ins when destroy function has been called.
811  *
812  * @param data an opaque pointer to plug-in instance data
813  */
814  void (*destroy)(void *data);
815 
816 };
817 
818 /*@}*/
819 
820 
821 /* ------------------------------------------------------------------------
822  * Function declarations
823  * ----------------------------------------------------------------------*/
824 
825 /**
826  * @defgroup cFuncs Functions
827  *
828  * C API functions. The C-Pluff C API functions and
829  * any data exposed by them are generally thread-safe if the library has been
830  * compiled with multi-threading support. The
831  * @ref cFuncsInit "framework initialization functions"
832  * are exceptions, they are not thread-safe.
833  */
834 
835 /**
836  * @defgroup cFuncsFrameworkInfo Framework information
837  * @ingroup cFuncs
838  *
839  * These functions can be used to query runtime information about the
840  * linked in C-Pluff implementation. They may be used by the main program or
841  * by a plug-in runtime.
842  */
843 /*@{*/
844 
845 /**
846  * Returns the release version string of the linked in C-Pluff
847  * implementation.
848  *
849  * @return the C-Pluff release version string
850  */
851 CP_C_API const char *cp_get_version(void) CP_GCC_PURE;
852 
853 /**
854  * Returns the canonical host type associated with the linked in C-Pluff implementation.
855  * A multi-platform installation manager could use this information to
856  * determine what plug-in versions to install.
857  *
858  * @return the canonical host type
859  */
860 CP_C_API const char *cp_get_host_type(void) CP_GCC_PURE;
861 
862 /*@}*/
863 
864 
865 /**
866  * @defgroup cFuncsInit Framework initialization
867  * @ingroup cFuncs
868  *
869  * These functions are used for framework initialization.
870  * They are intended to be used by the main program. These functions are
871  * not thread safe.
872  */
873 /*@{*/
874 
875 /**
876  * Sets the fatal error handler called on non-recoverable errors. The default
877  * error handler prints the error message out to standard error and aborts
878  * the program. If the user specified error handler returns then the framework
879  * will abort the program. Setting NULL error handler will restore the default
880  * handler. This function is not thread-safe and it should be called
881  * before initializing the framework to catch all fatal errors.
882  *
883  * @param error_handler the fatal error handler
884  */
886 
887 /**
888  * Initializes the plug-in framework. This function must be called
889  * by the main program before calling any other plug-in framework
890  * functions except @ref cFuncsFrameworkInfo "framework information" functions and
891  * ::cp_set_fatal_error_handler. This function may be
892  * called several times but it is not thread-safe. Library resources
893  * should be released by calling ::cp_destroy when the framework is
894  * not needed anymore.
895  *
896  * Additionally, to enable localization support, the main program should
897  * set the current locale using @code setlocale(LC_ALL, "") @endcode
898  * before calling this function.
899  *
900  * @return @ref CP_OK (zero) on success or error code on failure
901  */
902 CP_C_API cp_status_t cp_init(void);
903 
904 /**
905  * Destroys the plug-in framework and releases the resources used by it.
906  * The plug-in framework is only destroyed after this function has
907  * been called as many times as ::cp_init. This function is not
908  * thread-safe. Plug-in framework functions other than ::cp_init,
909  * ::cp_get_framework_info and ::cp_set_fatal_error_handler
910  * must not be called after the plug-in framework has been destroyed.
911  * All contexts are destroyed and all data references returned by the
912  * framework become invalid.
913  */
914 CP_C_API void cp_destroy(void);
915 
916 /*@}*/
917 
918 
919 /**
920  * @defgroup cFuncsContext Plug-in context initialization
921  * @ingroup cFuncs
922  *
923  * These functions are used to manage plug-in contexts from the main
924  * program perspective. They are not intended to be used by a plug-in runtime.
925  * From the main program perspective a plug-in context is a container for
926  * installed plug-ins. There can be several plug-in context instances if there
927  * are several independent sets of plug-ins. However, different plug-in
928  * contexts are not very isolated from each other in practice because the
929  * global symbols exported by a plug-in runtime in one context are visible to
930  * all plug-ins in all context instances.
931  */
932 /*@{*/
933 
934 /**
935  * Creates a new plug-in context which can be used as a container for plug-ins.
936  * Plug-ins are loaded and installed into a specific context. The main
937  * program may have more than one plug-in context but the plug-ins that
938  * interact with each other should be placed in the same context. The
939  * resources associated with the context are released by calling
940  * ::cp_destroy_context when the context is not needed anymore. Remaining
941  * contexts are automatically destroyed when the plug-in framework is
942  * destroyed.
943  *
944  * @param status pointer to the location where status code is to be stored, or NULL
945  * @return the newly created plugin context, or NULL on failure
946  */
947 CP_C_API cp_context_t * cp_create_context(cp_status_t *status);
948 
949 /**
950  * Destroys the specified plug-in context and releases the associated resources.
951  * Stops and uninstalls all plug-ins in the context. The context must not be
952  * accessed after calling this function.
953  *
954  * @param ctx the context to be destroyed
955  */
957 
958 /**
959  * Registers a plug-in collection with a plug-in context. A plug-in collection
960  * is a directory that has plug-ins as its immediate subdirectories. The
961  * plug-in context will scan the directory when ::cp_scan_plugins is called.
962  * Returns @ref CP_OK if the directory has already been registered. A plug-in
963  * collection can be unregistered using ::cp_unregister_pcollection or
964  * ::cp_unregister_pcollections.
965  *
966  * @param ctx the plug-in context
967  * @param dir the directory
968  * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if insufficient memory
969  */
970 CP_C_API cp_status_t cp_register_pcollection(cp_context_t *ctx, const char *dir) CP_GCC_NONNULL(1, 2);
971 
972 /**
973  * Unregisters a previously registered plug-in collection from a
974  * plug-in context. Plug-ins already loaded from the collection are not
975  * affected. Does nothing if the directory has not been registered.
976  * Plug-in collections can be registered using ::cp_register_pcollection.
977  *
978  * @param ctx the plug-in context
979  * @param dir the previously registered directory
980  */
981 CP_C_API void cp_unregister_pcollection(cp_context_t *ctx, const char *dir) CP_GCC_NONNULL(1, 2);
982 
983 /**
984  * Unregisters all plug-in collections from a plug-in context.
985  * Plug-ins already loaded are not affected. Plug-in collections can
986  * be registered using ::cp_register_pcollection.
987  *
988  * @param ctx the plug-in context
989  */
990 CP_C_API void cp_unregister_pcollections(cp_context_t *ctx) CP_GCC_NONNULL(1);
991 
992 /*@}*/
993 
994 
995 /**
996  * @defgroup cFuncsLogging Logging
997  * @ingroup cFuncs
998  *
999  * These functions can be used to receive and emit log messages related
1000  * to a particular plug-in context. They can be used by the main program
1001  * or by a plug-in runtime.
1002  */
1003 /*@{*/
1004 
1005 /**
1006  * Registers a logger with a plug-in context or updates the settings of a
1007  * registered logger. The logger will receive selected log messages.
1008  * If the specified logger is not yet known, a new logger registration
1009  * is made, otherwise the settings for the existing logger are updated.
1010  * The logger can be unregistered using ::cp_unregister_logger and it is
1011  * automatically unregistered when the registering plug-in is stopped or
1012  * when the context is destroyed.
1013  *
1014  * @param ctx the plug-in context to log
1015  * @param logger the logger function to be called
1016  * @param user_data the user data pointer passed to the logger
1017  * @param min_severity the minimum severity of messages passed to logger
1018  * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if insufficient memory
1019  */
1020 CP_C_API cp_status_t cp_register_logger(cp_context_t *ctx, cp_logger_func_t logger, void *user_data, cp_log_severity_t min_severity) CP_GCC_NONNULL(1, 2);
1021 
1022 /**
1023  * Removes a logger registration.
1024  *
1025  * @param ctx the plug-in context
1026  * @param logger the logger function to be unregistered
1027  */
1028 CP_C_API void cp_unregister_logger(cp_context_t *ctx, cp_logger_func_t logger) CP_GCC_NONNULL(1, 2);
1029 
1030 /**
1031  * Emits a new log message.
1032  *
1033  * @param ctx the plug-in context
1034  * @param severity the severity of the event
1035  * @param msg the log message (possibly localized)
1036  */
1037 CP_C_API void cp_log(cp_context_t *ctx, cp_log_severity_t severity, const char *msg) CP_GCC_NONNULL(1, 3);
1038 
1039 /**
1040  * Returns whether a message of the specified severity would get logged.
1041  *
1042  * @param ctx the plug-in context
1043  * @param severity the target logging severity
1044  * @return whether a message of the specified severity would get logged
1045  */
1046 CP_C_API int cp_is_logged(cp_context_t *ctx, cp_log_severity_t severity) CP_GCC_NONNULL(1);
1047 
1048 /*@}*/
1049 
1050 
1051 /**
1052  * @defgroup cFuncsPlugin Plug-in management
1053  * @ingroup cFuncs
1054  *
1055  * These functions can be used to manage plug-ins. They are intended to be
1056  * used by the main program.
1057  */
1058 /*@{*/
1059 
1060 /**
1061  * Loads a plug-in descriptor from the specified plug-in installation
1062  * path and returns information about the plug-in. The plug-in descriptor
1063  * is validated during loading. Possible loading errors are reported via the
1064  * specified plug-in context. The plug-in is not installed to the context.
1065  * If operation fails or the descriptor
1066  * is invalid then NULL is returned. The caller must release the returned
1067  * information by calling ::cp_release_plugin_info when it does not
1068  * need the information anymore, typically after installing the plug-in.
1069  * The returned plug-in information must not be modified.
1070  *
1071  * @param ctx the plug-in context
1072  * @param path the installation path of the plug-in
1073  * @param status a pointer to the location where status code is to be stored, or NULL
1074  * @return pointer to the information structure or NULL if error occurs
1075  */
1076 CP_C_API cp_plugin_info_t * cp_load_plugin_descriptor(cp_context_t *ctx, const char *path, cp_status_t *status) CP_GCC_NONNULL(1, 2);
1077 
1078 /**
1079  * Loads a plug-in descriptor from the specified block of memory and returns
1080  * information about the plug-in. The plug-in descriptor
1081  * is validated during loading. Possible loading errors are reported via the
1082  * specified plug-in context. The plug-in is not installed to the context.
1083  * If operation fails or the descriptor
1084  * is invalid then NULL is returned. The caller must release the returned
1085  * information by calling ::cp_release_info when it does not
1086  * need the information anymore, typically after installing the plug-in.
1087  * The returned plug-in information must not be modified.
1088  *
1089  * @param ctx the plug-in context
1090  * @param buffer the buffer containing the plug-in descriptor.
1091  * @param buffer_len the length of the buffer.
1092  * @param status a pointer to the location where status code is to be stored, or NULL
1093  * @return pointer to the information structure or NULL if error occurs
1094  */
1095 CP_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);
1096 
1097 /**
1098  * Installs the plug-in described by the specified plug-in information
1099  * structure to the specified plug-in context. The plug-in information
1100  * must have been loaded using ::cp_load_plugin_descriptor with the same
1101  * plug-in context.
1102  * The installation fails on #CP_ERR_CONFLICT if the context already
1103  * has an installed plug-in with the same plug-in identifier. Installation
1104  * also fails if the plug-in tries to install an extension point which
1105  * conflicts with an already installed extension point.
1106  * The plug-in information must not be modified but it is safe to call
1107  * ::cp_release_plugin_info after the plug-in has been installed.
1108  *
1109  * @param ctx the plug-in context
1110  * @param pi plug-in information structure
1111  * @return @ref CP_OK (zero) on success or an error code on failure
1112  */
1113 CP_C_API cp_status_t cp_install_plugin(cp_context_t *ctx, cp_plugin_info_t *pi) CP_GCC_NONNULL(1, 2);
1114 
1115 /**
1116  * Scans for plug-ins in the registered plug-in directories, installing
1117  * new plug-ins and upgrading installed plug-ins. This function can be used to
1118  * initially load the plug-ins and to later rescan for new plug-ins.
1119  *
1120  * When several versions of the same plug-in is available the most recent
1121  * version will be installed. The upgrade behavior depends on the specified
1122  * @ref cScanFlags "flags". If #CP_SP_UPGRADE is set then upgrades to installed plug-ins are
1123  * allowed. The old version is unloaded and the new version installed instead.
1124  * If #CP_SP_STOP_ALL_ON_UPGRADE is set then all active plug-ins are stopped
1125  * if any plug-ins are to be upgraded. If #CP_SP_STOP_ALL_ON_INSTALL is set then
1126  * all active plug-ins are stopped if any plug-ins are to be installed or
1127  * upgraded. Finally, if #CP_SP_RESTART_ACTIVE is set all currently active
1128  * plug-ins will be restarted after the changes (if they were stopped).
1129  *
1130  * When removing plug-in files from the plug-in directories, the
1131  * plug-ins to be removed must be first unloaded. Therefore this function
1132  * does not check for removed plug-ins.
1133  *
1134  * @param ctx the plug-in context
1135  * @param flags the bitmask of flags
1136  * @return @ref CP_OK (zero) on success or an error code on failure
1137  */
1138 CP_C_API cp_status_t cp_scan_plugins(cp_context_t *ctx, int flags) CP_GCC_NONNULL(1);
1139 
1140 /**
1141  * Starts a plug-in. Also starts any imported plug-ins. If the plug-in is
1142  * already starting then
1143  * this function blocks until the plug-in has started or failed to start.
1144  * If the plug-in is already active then this function returns immediately.
1145  * If the plug-in is stopping then this function blocks until the plug-in
1146  * has stopped and then starts the plug-in.
1147  *
1148  * @param ctx the plug-in context
1149  * @param id identifier of the plug-in to be started
1150  * @return @ref CP_OK (zero) on success or an error code on failure
1151  */
1152 CP_C_API cp_status_t cp_start_plugin(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1, 2);
1153 
1154 /**
1155  * Stops a plug-in. First stops any dependent plug-ins that are currently
1156  * active. Then stops the specified plug-in. If the plug-in is already
1157  * stopping then this function blocks until the plug-in has stopped. If the
1158  * plug-in is already stopped then this function returns immediately. If the
1159  * plug-in is starting then this function blocks until the plug-in has
1160  * started (or failed to start) and then stops the plug-in.
1161  *
1162  * @param ctx the plug-in context
1163  * @param id identifier of the plug-in to be stopped
1164  * @return @ref CP_OK (zero) on success or @ref CP_ERR_UNKNOWN if unknown plug-in
1165  */
1166 CP_C_API cp_status_t cp_stop_plugin(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1, 2);
1167 
1168 /**
1169  * Stops all active plug-ins.
1170  *
1171  * @param ctx the plug-in context
1172  */
1173 CP_C_API void cp_stop_plugins(cp_context_t *ctx) CP_GCC_NONNULL(1);
1174 
1175 /**
1176  * Uninstalls the specified plug-in. The plug-in is first stopped if it is active.
1177  * Then uninstalls the plug-in and any dependent plug-ins.
1178  *
1179  * @param ctx the plug-in context
1180  * @param id identifier of the plug-in to be unloaded
1181  * @return @ref CP_OK (zero) on success or @ref CP_ERR_UNKNOWN if unknown plug-in
1182  */
1183 CP_C_API cp_status_t cp_uninstall_plugin(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1, 2);
1184 
1185 /**
1186  * Uninstalls all plug-ins. All plug-ins are first stopped and then
1187  * uninstalled.
1188  *
1189  * @param ctx the plug-in context
1190  */
1191 CP_C_API void cp_uninstall_plugins(cp_context_t *ctx) CP_GCC_NONNULL(1);
1192 
1193 /*@}*/
1194 
1195 
1196 /**
1197  * @defgroup cFuncsPluginInfo Plug-in and extension information
1198  * @ingroup cFuncs
1199  *
1200  * These functions can be used to query information about the installed
1201  * plug-ins, extension points and extensions or to listen for plug-in state
1202  * changes. They may be used by the main program or by a plug-in runtime.
1203  */
1204 /*@{*/
1205 
1206 /**
1207  * Returns static information about the specified plug-in. The returned
1208  * information must not be modified and the caller must
1209  * release the information by calling ::cp_release_info when the
1210  * information is not needed anymore. When a plug-in runtime calls this
1211  * function it may pass NULL as the identifier to get information about the
1212  * plug-in itself.
1213  *
1214  * @param ctx the plug-in context
1215  * @param id identifier of the plug-in to be examined or NULL for self
1216  * @param status a pointer to the location where status code is to be stored, or NULL
1217  * @return pointer to the information structure or NULL on failure
1218  */
1219 CP_C_API cp_plugin_info_t * cp_get_plugin_info(cp_context_t *ctx, const char *id, cp_status_t *status) CP_GCC_NONNULL(1);
1220 
1221 /**
1222  * Returns static information about the installed plug-ins. The returned
1223  * information must not be modified and the caller must
1224  * release the information by calling ::cp_release_info when the
1225  * information is not needed anymore.
1226  *
1227  * @param ctx the plug-in context
1228  * @param status a pointer to the location where status code is to be stored, or NULL
1229  * @param num a pointer to the location where the number of returned plug-ins is stored, or NULL
1230  * @return pointer to a NULL-terminated list of pointers to plug-in information
1231  * or NULL on failure
1232  */
1233 CP_C_API cp_plugin_info_t ** cp_get_plugins_info(cp_context_t *ctx, cp_status_t *status, int *num) CP_GCC_NONNULL(1);
1234 
1235 /**
1236  * Returns static information about the currently installed extension points.
1237  * The returned information must not be modified and the caller must
1238  * release the information by calling ::cp_release_info when the
1239  * information is not needed anymore.
1240  *
1241  * @param ctx the plug-in context
1242  * @param status a pointer to the location where status code is to be stored, or NULL
1243  * @param num filled with the number of returned extension points, if non-NULL
1244  * @return pointer to a NULL-terminated list of pointers to extension point
1245  * information or NULL on failure
1246  */
1247 CP_C_API cp_ext_point_t ** cp_get_ext_points_info(cp_context_t *ctx, cp_status_t *status, int *num) CP_GCC_NONNULL(1);
1248 
1249 /**
1250  * Returns static information about the currently installed extension points.
1251  * The returned information must not be modified and the caller must
1252  * release the information by calling ::cp_release_info when the
1253  * information is not needed anymore.
1254  *
1255  * @param ctx the plug-in context
1256  * @param extpt_id the extension point identifier or NULL for all extensions
1257  * @param status a pointer to the location where status code is to be stored, or NULL
1258  * @param num a pointer to the location where the number of returned extension points is to be stored, or NULL
1259  * @return pointer to a NULL-terminated list of pointers to extension
1260  * information or NULL on failure
1261  */
1262 CP_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);
1263 
1264 /**
1265  * Releases a previously obtained reference counted information object. The
1266  * documentation for functions returning such information refers
1267  * to this function. The information must not be accessed after it has
1268  * been released. The framework uses reference counting to deallocate
1269  * the information when it is not in use anymore.
1270  *
1271  * @param ctx the plug-in context
1272  * @param info the information to be released
1273  */
1274 CP_C_API void cp_release_info(cp_context_t *ctx, void *info) CP_GCC_NONNULL(1, 2);
1275 
1276 /**
1277  * Returns the current state of the specified plug-in. Returns
1278  * #CP_PLUGIN_UNINSTALLED if the specified plug-in identifier is unknown.
1279  *
1280  * @param ctx the plug-in context
1281  * @param id the plug-in identifier
1282  * @return the current state of the plug-in
1283  */
1284 CP_C_API cp_plugin_state_t cp_get_plugin_state(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1, 2);
1285 
1286 /**
1287  * Registers a plug-in listener with a plug-in context. The listener is called
1288  * synchronously immediately after a plug-in state change. There can be several
1289  * listeners registered with the same context. A plug-in listener can be
1290  * unregistered using ::cp_unregister_plistener and it is automatically
1291  * unregistered when the registering plug-in is stopped or when the context
1292  * is destroyed.
1293  *
1294  * @param ctx the plug-in context
1295  * @param listener the plug-in listener to be added
1296  * @param user_data user data pointer supplied to the listener
1297  * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if out of resources
1298  */
1299 CP_C_API cp_status_t cp_register_plistener(cp_context_t *ctx, cp_plugin_listener_func_t listener, void *user_data) CP_GCC_NONNULL(1, 2);
1300 
1301 /**
1302  * Removes a plug-in listener from a plug-in context. Does nothing if the
1303  * specified listener was not registered.
1304  *
1305  * @param ctx the plug-in context
1306  * @param listener the plug-in listener to be removed
1307  */
1308 CP_C_API void cp_unregister_plistener(cp_context_t *ctx, cp_plugin_listener_func_t listener) CP_GCC_NONNULL(1, 2);
1309 
1310 /**
1311  * Traverses a configuration element tree and returns the specified element.
1312  * The target element is specified by a base element and a relative path from
1313  * the base element to the target element. The path includes element names
1314  * separated by slash '/'. Two dots ".." can be used to designate a parent
1315  * element. Returns NULL if the specified element does not exist. If there are
1316  * several subelements with the same name, this function chooses the first one
1317  * when traversing the tree.
1318  *
1319  * @param base the base configuration element
1320  * @param path the path to the target element
1321  * @return the target element or NULL if nonexisting
1322  */
1323 CP_C_API cp_cfg_element_t * cp_lookup_cfg_element(cp_cfg_element_t *base, const char *path) CP_GCC_PURE CP_GCC_NONNULL(1, 2);
1324 
1325 /**
1326  * Traverses a configuration element tree and returns the value of the
1327  * specified element or attribute. The target element or attribute is specified
1328  * by a base element and a relative path from the base element to the target
1329  * element or attributes. The path includes element names
1330  * separated by slash '/'. Two dots ".." can be used to designate a parent
1331  * element. The path may end with '@' followed by an attribute name
1332  * to select an attribute. Returns NULL if the specified element or attribute
1333  * does not exist or does not have a value. If there are several subelements
1334  * with the same name, this function chooses the first one when traversing the
1335  * tree.
1336  *
1337  * @param base the base configuration element
1338  * @param path the path to the target element
1339  * @return the value of the target element or attribute or NULL
1340  */
1341 CP_C_API char * cp_lookup_cfg_value(cp_cfg_element_t *base, const char *path) CP_GCC_PURE CP_GCC_NONNULL(1, 2);
1342 
1343 /*@}*/
1344 
1345 
1346 /**
1347  * @defgroup cFuncsPluginExec Plug-in execution
1348  * @ingroup cFuncs
1349  *
1350  * These functions support a plug-in controlled execution model. Started plug-ins can
1351  * use ::cp_run_function to register @ref cp_run_func_t "a run function" which is called when the
1352  * main program calls ::cp_run_plugins or ::cp_run_plugins_step. A run
1353  * function should do a finite chunk of work and then return telling whether
1354  * there is more work to be done. A run function is automatically unregistered
1355  * when the plug-in is stopped. Run functions make it possible for plug-ins
1356  * to control the flow of execution or they can be used as a coarse
1357  * way of task switching if there is no multi-threading support.
1358  *
1359  * The C-Pluff distribution includes a generic main program, cpluff-loader,
1360  * which only acts as a plug-in loader. It loads and starts up the
1361  * specified plug-ins, passing any additional startup arguments to them and
1362  * then just calls run functions of the plug-ins. This
1363  * makes it is possible to put all the application specific logic in
1364  * plug-ins. Application does not necessarily need a main program of its own.
1365  *
1366  * It is also safe, from framework perspective, to call these functions from
1367  * multiple threads. Run functions may then be executed in parallel threads.
1368  */
1369 /*@{*/
1370 
1371 /**
1372  * Registers a new run function. The plug-in instance data pointer is given to
1373  * the run function as a parameter. The run function must return zero if it has
1374  * finished its work or non-zero if it should be called again later. The run
1375  * function is unregistered when it returns zero. Plug-in framework functions
1376  * stopping the registering plug-in must not be called from within a run
1377  * function. This function does nothing if the specified run
1378  * function is already registered for the calling plug-in instance.
1379  *
1380  * @param ctx the plug-in context of the registering plug-in
1381  * @param runfunc the run function to be registered
1382  * @return @ref CP_OK (zero) on success or an error code on failure
1383  */
1384 CP_C_API cp_status_t cp_run_function(cp_context_t *ctx, cp_run_func_t runfunc) CP_GCC_NONNULL(1, 2);
1385 
1386 /**
1387  * Runs the started plug-ins as long as there is something to run.
1388  * This function calls repeatedly run functions registered by started plug-ins
1389  * until there are no more active run functions. This function is normally
1390  * called by a thin main proram, a loader, which loads plug-ins, starts some
1391  * plug-ins and then passes control over to the started plug-ins.
1392  *
1393  * @param ctx the plug-in context containing the plug-ins
1394  */
1395 CP_C_API void cp_run_plugins(cp_context_t *ctx) CP_GCC_NONNULL(1);
1396 
1397 /**
1398  * Runs one registered run function. This function calls one
1399  * active run function registered by a started plug-in. When the run function
1400  * returns this function also returns and passes control back to the main
1401  * program. The return value can be used to determine whether there are any
1402  * active run functions left. This function does nothing if there are no active
1403  * registered run functions.
1404  *
1405  * @param ctx the plug-in context containing the plug-ins
1406  * @return whether there are active run functions waiting to be run
1407  */
1408 CP_C_API int cp_run_plugins_step(cp_context_t *ctx) CP_GCC_NONNULL(1);
1409 
1410 /**
1411  * Sets startup arguments for the specified plug-in context. Like for usual
1412  * C main functions, the first argument is expected to be the name of the
1413  * program being executed or an empty string and the argument array should be
1414  * terminated by NULL entry. If the main program is
1415  * about to pass startup arguments to plug-ins it should call this function
1416  * before starting any plug-ins in the context. The arguments are not copied
1417  * and the caller is responsible for keeping the argument data available once
1418  * the arguments have been set until the context is destroyed. Plug-ins can
1419  * access the startup arguments using ::cp_get_context_args.
1420  *
1421  * @param ctx the plug-in context
1422  * @param argv a NULL-terminated array of arguments
1423  */
1424 CP_C_API void cp_set_context_args(cp_context_t *ctx, char **argv) CP_GCC_NONNULL(1, 2);
1425 
1426 /**
1427  * Returns the startup arguments associated with the specified
1428  * plug-in context. This function is intended to be used by a plug-in runtime.
1429  * Startup arguments are set by the main program using ::cp_set_context_args.
1430  * The returned argument count is zero and the array pointer is NULL if no
1431  * arguments have been set.
1432  *
1433  * @param ctx the plug-in context
1434  * @param argc a pointer to a location where the number of startup arguments is stored, or NULL for none
1435  * @return an argument array terminated by NULL or NULL if not set
1436  */
1437 CP_C_API char **cp_get_context_args(cp_context_t *ctx, int *argc) CP_GCC_NONNULL(1);
1438 
1439 /*@}*/
1440 
1441 
1442 /**
1443  * @defgroup cFuncsSymbols Dynamic symbols
1444  * @ingroup cFuncs
1445  *
1446  * These functions can be used to dynamically access symbols exported by the
1447  * plug-ins. They are intended to be used by a plug-in runtime or by the main
1448  * program.
1449  */
1450 /*@{*/
1451 
1452 /**
1453  * Defines a context specific symbol. If a plug-in has symbols which have
1454  * a plug-in instance specific value then the plug-in should define those
1455  * symbols when it is started. The defined symbols are cleared
1456  * automatically when the plug-in instance is stopped. Symbols can not be
1457  * redefined.
1458  *
1459  * @param ctx the plug-in context
1460  * @param name the name of the symbol
1461  * @param ptr pointer value for the symbol
1462  * @return @ref CP_OK (zero) on success or a status code on failure
1463  */
1464 CP_C_API cp_status_t cp_define_symbol(cp_context_t *ctx, const char *name, void *ptr) CP_GCC_NONNULL(1, 2, 3);
1465 
1466 /**
1467  * Resolves a symbol provided by the specified plug-in. The plug-in is started
1468  * automatically if it is not already active. The symbol may be context
1469  * specific or global. The framework first looks for a context specific
1470  * symbol and then falls back to resolving a global symbol exported by the
1471  * plug-in runtime library. The symbol can be released using
1472  * ::cp_release_symbol when it is not needed anymore. Pointers obtained from
1473  * this function must not be passed on to other plug-ins or the main
1474  * program.
1475  *
1476  * When a plug-in runtime calls this function the plug-in framework creates
1477  * a dynamic dependency from the symbol using plug-in to the symbol
1478  * defining plug-in. The symbol using plug-in is stopped automatically if the
1479  * symbol defining plug-in is about to be stopped. If the symbol using plug-in
1480  * does not explicitly release the symbol then it is automatically released
1481  * after a call to the stop function. It is not safe to refer to a dynamically
1482  * resolved symbol in the stop function except to release it using
1483  * ::cp_release_symbol.
1484  *
1485  * When the main program calls this function it is the responsibility of the
1486  * main program to always release the symbol before the symbol defining plug-in
1487  * is stopped. It is a fatal error if the symbol is not released before the
1488  * symbol defining plug-in is stopped.
1489  *
1490  * @param ctx the plug-in context
1491  * @param id the identifier of the symbol defining plug-in
1492  * @param name the name of the symbol
1493  * @param status a pointer to the location where the status code is to be stored, or NULL
1494  * @return the pointer associated with the symbol or NULL on failure
1495  */
1496 CP_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);
1497 
1498 /**
1499  * Releases a previously obtained symbol. The pointer must not be used after
1500  * the symbol has been released. The symbol is released
1501  * only after as many calls to this function as there have been for
1502  * ::cp_resolve_symbol for the same plug-in and symbol.
1503  *
1504  * @param ctx the plug-in context
1505  * @param ptr the pointer associated with the symbol
1506  */
1507 CP_C_API void cp_release_symbol(cp_context_t *ctx, const void *ptr) CP_GCC_NONNULL(1, 2);
1508 
1509 /*@}*/
1510 
1511 
1512 #ifdef __cplusplus
1513 }
1514 #endif /*__cplusplus*/
1515 
1516 #endif /*CPLUFF_H_*/
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.
Plug-in is not installed.
Definition: cpluff.h:181
Extension structure captures information about an extension.
Definition: cpluff.h:611
cp_extension_t * extensions
An array of num_extensions extensions provided by this plug-in.
Definition: cpluff.h:521
char * version
An optional release version string.
Definition: cpluff.h:420
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 void cp_run_plugins(cp_context_t *ctx)
Runs the started plug-ins as long as there is something to run.
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 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_unregister_pcollections(cp_context_t *ctx)
Unregisters all plug-in collections from a plug-in context.
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:358
CP_IMPORT void cp_release_info(cp_context_t *ctx, void *info)
Releases a previously obtained reference counted information object.
cp_cfg_element_t * parent
A pointer to the parent element or NULL if this is a root element.
Definition: cpluff.h:692
CP_IMPORT const char * cp_get_version(void)
Returns the release version string of the linked in C-Pluff implementation.
char * local_id
An optional local identifier uniquely identifying the extension within the host plug-in.
Definition: cpluff.h:632
The specified object is unknown to the framework.
Definition: cpluff.h:145
Container for plug-in runtime information.
Definition: cpluff.h:734
CP_IMPORT void cp_log(cp_context_t *ctx, cp_log_severity_t severity, const char *msg)
Emits a new log message.
An I/O error occurred.
Definition: cpluff.h:148
Plug-in information structure captures information about a plug-in.
Definition: cpluff.h:396
CP_IMPORT cp_status_t cp_define_symbol(cp_context_t *ctx, const char *name, void *ptr)
Defines a context specific symbol.
Used for messages reporting errors.
Definition: cpluff.h:253
Plug-in runtime signaled an error.
Definition: cpluff.h:160
cp_plugin_state_t
An enumeration of possible plug-in states.
Definition: cpluff.h:175
unsigned int num_children
Number of children in the children array.
Definition: cpluff.h:698
Plug-in dependencies could not be satisfied.
Definition: cpluff.h:157
char * name
An optional extension name.
Definition: cpluff.h:647
Extension point structure captures information about an extension point.
Definition: cpluff.h:566
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 cp_status_t cp_init(void)
Initializes the plug-in framework.
CP_IMPORT cp_status_t cp_register_pcollection(cp_context_t *ctx, const char *dir)
Registers a plug-in collection with a plug-in context.
CP_IMPORT cp_status_t cp_uninstall_plugin(cp_context_t *ctx, const char *id)
Uninstalls the specified plug-in.
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.
char * identifier
An optional unique identifier of the extension.
Definition: cpluff.h:639
cp_status_t
An enumeration of status codes returned by API functions.
Definition: cpluff.h:133
void(* stop)(void *data)
A stop function called to stop a plugin instance.
Definition: cpluff.h:800
char * name
The name of the configuration element.
Definition: cpluff.h:673
char * api_bw_compatibility
Optional API compatibility information.
Definition: cpluff.h:465
CP_IMPORT void cp_release_symbol(cp_context_t *ctx, const void *ptr)
Releases a previously obtained symbol.
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 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_stop_plugin(cp_context_t *ctx, const char *id)
Stops a plug-in.
CP_IMPORT cp_status_t cp_start_plugin(cp_context_t *ctx, const char *id)
Starts a plug-in.
unsigned int index
The index of this element among its siblings (0-based).
Definition: cpluff.h:695
void(* cp_fatal_error_func_t)(const char *msg)
A fatal error handler for handling unrecoverable errors.
Definition: cpluff.h:369
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.
unsigned int num_extensions
Number of extensions in extensions array.
Definition: cpluff.h:514
cp_cfg_element_t * children
An array of num_children childrens of this element.
Definition: cpluff.h:704
char * ext_point_id
The unique identifier of the extension point this extension is attached to.
Definition: cpluff.h:625
int(* start)(void *data)
A start function called to start a plug-in instance.
Definition: cpluff.h:775
char * req_cpluff_version
Optional C-Pluff version requirement.
Definition: cpluff.h:475
unsigned int num_ext_points
Number of extension points in ext_points array.
Definition: cpluff.h:504
char * identifier
The unique identifier of the extension point.
Definition: cpluff.h:587
unsigned int num_imports
Number of import entries in the imports array.
Definition: cpluff.h:478
CP_IMPORT int cp_run_plugins_step(cp_context_t *ctx)
Runs one registered run function.
Plug-in dependencies have been resolved.
Definition: cpluff.h:202
Common defines shared by C-Pluff C and C++ APIs.
CP_IMPORT void cp_stop_plugins(cp_context_t *ctx)
Stops all active plug-ins.
Malformed plug-in descriptor was encountered when loading a plug-in.
Definition: cpluff.h:151
Operation was performed successfully (equals to zero).
Definition: cpluff.h:139
Not enough memory or other operating system resources available.
Definition: cpluff.h:142
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...
char * value
An optional value of this configuration element.
Definition: cpluff.h:689
CP_IMPORT void cp_uninstall_plugins(cp_context_t *ctx)
Uninstalls all plug-ins.
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 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_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_unregister_plistener(cp_context_t *ctx, cp_plugin_listener_func_t listener)
Removes a plug-in listener from a plug-in context.
Plug-in is installed.
Definition: cpluff.h:190
char * abi_bw_compatibility
Optional ABI compatibility information.
Definition: cpluff.h:451
char * plugin_path
Path of the plugin directory or NULL if not known.
Definition: cpluff.h:438
cp_cfg_element_t * configuration
Extension configuration starting with the extension element.
Definition: cpluff.h:655
#define CP_GCC_PURE
Declares a function as pure function having no side effects.
Definition: cpluffdef.h:190
Plug-in has been successfully started and it has not yet been stopped.
Definition: cpluff.h:230
Used for messages warning about possible problems.
Definition: cpluff.h:250
cp_ext_point_t * ext_points
An array of num_ext_points extension points provided by this plug-in.
Definition: cpluff.h:511
CP_IMPORT void cp_unregister_logger(cp_context_t *ctx, cp_logger_func_t logger)
Removes a logger registration.
CP_IMPORT cp_status_t cp_run_function(cp_context_t *ctx, cp_run_func_t runfunc)
Registers a new run function.
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...
unsigned int num_atts
Number of attribute name, value pairs in the atts array.
Definition: cpluff.h:676
char * schema_path
An optional path to the extension schema definition.
Definition: cpluff.h:603
#define CP_C_API
Marks a symbol declaration to be part of the C-Pluff C API.
Definition: cpluff.h:61
cp_plugin_info_t * plugin
A pointer to plug-in information containing this extension point.
Definition: cpluff.h:573
char * name
An optional plug-in name.
Definition: cpluff.h:413
int optional
Is this import optional.
Definition: cpluff.h:557
CP_IMPORT void cp_set_context_args(cp_context_t *ctx, char **argv)
Sets startup arguments for the specified plug-in context.
char * version
An optional version requirement.
Definition: cpluff.h:546
char * name
An optional extension point name.
Definition: cpluff.h:595
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 char ** cp_get_context_args(cp_context_t *ctx, int *argc)
Returns the startup arguments associated with the specified plug-in context.
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
int(* cp_run_func_t)(void *plugin_data)
A run function registered by a plug-in to perform work.
Definition: cpluff.h:381
Plug-in is starting.
Definition: cpluff.h:213
CP_IMPORT void cp_destroy_context(cp_context_t *ctx)
Destroys the specified plug-in context and releases the associated resources.
Used for detailed debug messages.
Definition: cpluff.h:244
char ** atts
An array of pointers to alternating attribute names and values.
Definition: cpluff.h:682
A configuration element contains configuration information for an extension.
Definition: cpluff.h:667
char * provider_name
An optional provider name.
Definition: cpluff.h:429
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:344
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_destroy(void)
Destroys the plug-in framework and releases the resources used by it.
void(* destroy)(void *data)
A destroy function called to destroy a plug-in instance.
Definition: cpluff.h:814
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.
Plug-in or symbol conflicts with another plug-in or symbol.
Definition: cpluff.h:154
char * identifier
The obligatory unique identifier of the plugin.
Definition: cpluff.h:405
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 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_log_severity_t
An enumeration of possible message severities for framework logging.
Definition: cpluff.h:241
char * plugin_id
The identifier of the imported plug-in.
Definition: cpluff.h:536
Used for informational messages such as plug-in state changes.
Definition: cpluff.h:247
cp_plugin_info_t * plugin
A pointer to plug-in information containing this extension.
Definition: cpluff.h:618
Information about plug-in import.
Definition: cpluff.h:530
#define CP_GCC_NONNULL(...)
Specifies that some pointer arguments to a function should have non-NULL values.
Definition: cpluffdef.h:195
Plug-in is stopping.
Definition: cpluff.h:224
char * runtime_lib_name
The base name of the plug-in runtime library, or NULL if none.
Definition: cpluff.h:493
char * runtime_funcs_symbol
The symbol pointing to the plug-in runtime function information or NULL if none.
Definition: cpluff.h:501
cp_plugin_import_t * imports
An array of num_imports import entries.
Definition: cpluff.h:484

Generated on Fri Jan 1 2016 23:17:02 for C-Pluff C API by doxygen 1.8.6