1 /*-------------------------------------------------------------------------
2 * C-Pluff, a plug-in framework for C
3 * Copyright 2007 Johannes Lehtinen
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:
12 * The above copyright notice and this permission notice shall be included
13 * in all copies or substantial portions of the Software.
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 *-----------------------------------------------------------------------*/
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
37 * @defgroup cDefines Defines
38 * Preprocessor defines.
41 #include <cpluffdef.h>
45 #endif /*__cplusplus*/
48 /* ------------------------------------------------------------------------
50 * ----------------------------------------------------------------------*/
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.
61 #define CP_C_API CP_IMPORT
66 * @defgroup cScanFlags Flags for plug-in scanning
69 * These constants can be orred together for the flags
70 * parameter of ::cp_scan_plugins.
75 * This flag enables upgrades of installed plug-ins by unloading
76 * the old version and installing the new version.
78 #define CP_SP_UPGRADE 0x01
81 * This flag causes all plug-ins to be stopped before any
82 * plug-ins are to be upgraded.
84 #define CP_SP_STOP_ALL_ON_UPGRADE 0x02
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).
91 #define CP_SP_STOP_ALL_ON_INSTALL 0x04
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).
97 #define CP_SP_RESTART_ACTIVE 0x08
102 /* ------------------------------------------------------------------------
104 * ----------------------------------------------------------------------*/
107 * @defgroup cEnums Enumerations
108 * Constant value enumerations.
112 * @defgroup cTypedefs Typedefs
113 * Typedefs of various kind.
117 * @defgroup cStructs Data structures
118 * Data structure definitions.
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.
137 * Operation was performed successfully (equals to zero).
142 /** Not enough memory or other operating system resources available */
145 /** The specified object is unknown to the framework */
148 /** An I/O error occurred */
151 /** Malformed plug-in descriptor was encountered when loading a plug-in */
154 /** Plug-in or symbol conflicts with another plug-in or symbol. */
157 /** Plug-in dependencies could not be satisfied. */
160 /** Plug-in runtime signaled an error. */
167 * An enumeration of possible plug-in states. Plug-in states are controlled
168 * by @ref cFuncsPlugin "plug-in management functions". Plug-in states can be
169 * observed by @ref cp_register_plistener "registering" a
170 * @ref cp_plugin_listener_func_t "plug-in listener function"
171 * or by calling ::cp_get_plugin_state.
173 * @sa cp_plugin_listener_t
174 * @sa cp_get_plugin_state
176 enum cp_plugin_state_t
180 * Plug-in is not installed. No plug-in information has been
183 CP_PLUGIN_UNINSTALLED,
186 * Plug-in is installed. At this stage the plug-in information has
187 * been loaded but its dependencies to other plug-ins has not yet
188 * been resolved. The plug-in runtime has not been loaded yet.
189 * The extension points and extensions provided by the plug-in
190 * have been registered.
195 * Plug-in dependencies have been resolved. At this stage it has
196 * been verified that the dependencies of the plug-in are satisfied
197 * and the plug-in runtime has been loaded but it is not active
198 * (it has not been started or it has been stopped).
199 * Plug-in is resolved when a dependent plug-in is being
200 * resolved or before the plug-in is started. Plug-in is put
201 * back to installed stage if its dependencies are being
207 * Plug-in is starting. The plug-in has been resolved and the start
208 * function (if any) of the plug-in runtime is about to be called.
209 * A plug-in is started when explicitly requested by the main
210 * program or when a dependent plug-in is about to be started or when
211 * a dynamic symbol defined by the plug-in is being resolved. This state
212 * is omitted and the state changes directly from resolved to active
213 * if the plug-in runtime does not define a start function.
218 * Plug-in is stopping. The stop function (if any) of the plug-in
219 * runtime is about to be called. A plug-in is stopped if the start
220 * function fails or when stopping is explicitly
221 * requested by the main program or when its dependencies are being
222 * stopped. This state is omitted and the state changes directly from
223 * active to resolved if the plug-in runtime does not define a stop
229 * Plug-in has been successfully started and it has not yet been
238 * An enumeration of possible message severities for framework logging. These
239 * constants are used when passing a log message to a
240 * @ref cp_logger_func_t "logger function" and when
241 * @ref cp_register_logger "registering" a logger function.
243 enum cp_log_severity_t
246 /** Used for detailed debug messages */
249 /** Used for informational messages such as plug-in state changes */
252 /** Used for messages warning about possible problems */
255 /** Used for messages reporting errors */
266 * @defgroup cTypedefsOpaque Opaque types
268 * Opaque data type definitions.
273 * A plug-in context represents the co-operation environment of a set of
274 * plug-ins from the perspective of a particular participating plug-in or
275 * the perspective of the main program. It is used as an opaque handle to
276 * the shared resources but the framework also uses the context to identify
277 * the plug-in or the main program invoking framework functions. Therefore
278 * a plug-in should not generally expose its context instance to other
279 * plug-ins or the main program and neither should the main program
280 * expose its context instance to plug-ins. The main program creates
281 * plug-in contexts using ::cp_create_context and plug-ins receive their
282 * plug-in contexts via @ref cp_plugin_runtime_t::create.
284 typedef struct cp_context_t cp_context_t;
289 * @defgroup cTypedefsShorthand Shorthand type names
291 * Shorthand type names for structs and enumerations.
295 /** A type for cp_plugin_info_t structure. */
296 typedef struct cp_plugin_info_t cp_plugin_info_t;
298 /** A type for cp_plugin_import_t structure. */
299 typedef struct cp_plugin_import_t cp_plugin_import_t;
301 /** A type for cp_ext_point_t structure. */
302 typedef struct cp_ext_point_t cp_ext_point_t;
304 /** A type for cp_extension_t structure. */
305 typedef struct cp_extension_t cp_extension_t;
307 /** A type for cp_cfg_element_t structure. */
308 typedef struct cp_cfg_element_t cp_cfg_element_t;
310 /** A type for cp_plugin_runtime_t structure. */
311 typedef struct cp_plugin_runtime_t cp_plugin_runtime_t;
313 /** A type for cp_status_t enumeration. */
314 typedef enum cp_status_t cp_status_t;
316 /** A type for cp_plugin_state_t enumeration. */
317 typedef enum cp_plugin_state_t cp_plugin_state_t;
319 /** A type for cp_log_severity_t enumeration. */
320 typedef enum cp_log_severity_t cp_log_severity_t;
325 * @defgroup cTypedefsFuncs Callback function types
327 * Typedefs for client supplied callback functions.
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.
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
347 typedef void (*cp_plugin_listener_func_t)(const char *plugin_id, cp_plugin_state_t old_state,
348 cp_plugin_state_t new_state, void *user_data);
351 * A logger function called to log selected plug-in framework messages. The
352 * messages may be localized. Plug-in framework API functions must not
353 * be called from within a logger function invocation. In a multi-threaded
354 * environment logger function invocations are serialized by the framework.
355 * Logger functions are registered using ::cp_register_logger.
357 * @param severity the severity of the message
358 * @param msg the message to be logged, possibly localized
359 * @param apid the identifier of the activating plug-in or NULL for the main program
360 * @param user_data the user data pointer given when the logger was registered
362 typedef void (*cp_logger_func_t)(cp_log_severity_t severity, const char *msg, const char *apid,
366 * A fatal error handler for handling unrecoverable errors. If the error
367 * handler returns then the framework aborts the program. Plug-in framework
368 * API functions must not be called from within a fatal error handler
369 * invocation. The fatal error handler function is set using
370 * ::cp_set_fatal_error_handler.
372 * @param msg the possibly localized error message
374 typedef void (*cp_fatal_error_func_t)(const char *msg);
377 * A run function registered by a plug-in to perform work.
378 * The run function should perform a finite chunk of work and it should
379 * return a non-zero value if there is more work to be done. Run functions
380 * are registered using ::cp_run_function and the usage is discussed in
381 * more detail in the @ref cFuncsPluginExec "serial execution" section.
383 * @param plugin_data the plug-in instance data pointer
384 * @return non-zero if there is more work to be done or zero if finished
386 typedef int (*cp_run_func_t)(void *plugin_data);
391 /* Data structures */
395 * Plug-in information structure captures information about a plug-in. This
396 * information can be loaded from a plug-in descriptor using
397 * ::cp_load_plugin_descriptor. Information about installed plug-ins can
398 * be obtained using ::cp_get_plugin_info and ::cp_get_plugins_info. This
399 * structure corresponds to the @a plugin element in a plug-in descriptor.
401 struct cp_plugin_info_t
405 * The obligatory unique identifier of the plugin. A recommended way
406 * to generate identifiers is to use domain name service (DNS) prefixes
407 * (for example, org.cpluff.ExamplePlugin) to avoid naming conflicts. This
408 * corresponds to the @a id attribute of the @a plugin element in a plug-in
414 * An optional plug-in name. NULL if not available. The plug-in name is
415 * intended only for display purposes and the value can be localized.
416 * This corresponds to the @a name attribute of the @a plugin element in
417 * a plug-in descriptor.
422 * An optional release version string. NULL if not available. This
423 * corresponds to the @a version attribute of the @a plugin element in
424 * a plug-in descriptor.
429 * An optional provider name. NULL if not available. This is the name of
430 * the author or the organization providing the plug-in. The
431 * provider name is intended only for display purposes and the value can
432 * be localized. This corresponds to the @a provider-name attribute of the
433 * @a plugin element in a plug-in descriptor.
438 * Path of the plugin directory or NULL if not known. This is the
439 * (absolute or relative) path to the plug-in directory containing
440 * plug-in data and the plug-in runtime library. The value corresponds
441 * to the path specified to ::cp_load_plugin_descriptor when loading
447 * Optional ABI compatibility information. NULL if not available.
448 * This is the earliest version of the plug-in interface the current
449 * interface is backwards compatible with when it comes to the application
450 * binary interface (ABI) of the plug-in. That is, plug-in clients compiled against
451 * any plug-in interface version from @a abi_bw_compatibility to
452 * @ref version (inclusive) can use the current version of the plug-in
453 * binary. This describes binary or runtime compatibility.
454 * The value corresponds to the @a abi-compatibility
455 * attribute of the @a backwards-compatibility element in a plug-in descriptor.
457 char *abi_bw_compatibility;
460 * Optional API compatibility information. NULL if not available.
461 * This is the earliest version of the plug-in interface the current
462 * interface is backwards compatible with when it comes to the
463 * application programming interface (API) of the plug-in. That is,
464 * plug-in clients written for any plug-in interface version from
465 * @a api_bw_compatibility to @ref version (inclusive) can be compiled
466 * against the current version of the plug-in API. This describes
467 * source or build time compatibility. The value corresponds to the
468 * @a api-compatibility attribute of the @a backwards-compatibility
469 * element in a plug-in descriptor.
471 char *api_bw_compatibility;
474 * Optional C-Pluff version requirement. NULL if not available.
475 * This is the version of the C-Pluff implementation the plug-in was
476 * compiled against. It is used to determine the compatibility of
477 * the plug-in runtime and the linked in C-Pluff implementation. Any
478 * C-Pluff version that is backwards compatible on binary level with the
479 * specified version fulfills the requirement.
481 char *req_cpluff_version;
489 /** Number of import entries in the @ref imports array. */
490 unsigned int num_imports;
493 * An array of @ref num_imports import entries. These correspond to
494 * @a import elements in a plug-in descriptor.
496 cp_plugin_import_t *imports;
499 * The base name of the plug-in runtime library, or NULL if none.
500 * A platform specific prefix (for example, "lib") and an extension
501 * (for example, ".dll" or ".so") may be added to the base name.
502 * This corresponds to the @a library attribute of the
503 * @a runtime element in a plug-in descriptor.
505 char *runtime_lib_name;
508 * The symbol pointing to the plug-in runtime function information or
509 * NULL if none. The symbol with this name should point to an instance of
510 * @ref cp_plugin_runtime_t structure. This corresponds to the
511 * @a funcs attribute of the @a runtime element in a plug-in descriptor.
513 char *runtime_funcs_symbol;
515 /** Number of extension points in @ref ext_points array. */
516 unsigned int num_ext_points;
519 * An array of @ref num_ext_points extension points provided by this
520 * plug-in. These correspond to @a extension-point elements in a
521 * plug-in descriptor.
523 cp_ext_point_t *ext_points;
525 /** Number of extensions in @ref extensions array. */
526 unsigned int num_extensions;
529 * An array of @ref num_extensions extensions provided by this
530 * plug-in. These correspond to @a extension elements in a plug-in
533 cp_extension_t *extensions;
539 * Information about plug-in import. Plug-in import structures are
540 * contained in @ref cp_plugin_info_t::imports.
542 struct cp_plugin_import_t
546 * The identifier of the imported plug-in. This corresponds to the
547 * @a plugin attribute of the @a import element in a plug-in descriptor.
552 * An optional version requirement. NULL if no version requirement.
553 * This is the version of the imported plug-in the importing plug-in was
554 * compiled against. Any version of the imported plug-in that is
555 * backwards compatible with this version fulfills the requirement.
556 * This corresponds to the @a if-version attribute of the @a import
557 * element in a plug-in descriptor.
562 * Is this import optional. 1 for optional and 0 for mandatory import.
563 * An optional import causes the imported plug-in to be started if it is
564 * available but does not stop the importing plug-in from starting if the
565 * imported plug-in is not available. If the imported plug-in is available
566 * but the API version conflicts with the API version requirement then the
567 * importing plug-in fails to start. This corresponds to the @a optional
568 * attribute of the @a import element in a plug-in descriptor.
575 * Extension point structure captures information about an extension
576 * point. Extension point structures are contained in
577 * @ref cp_plugin_info_t::ext_points.
579 struct cp_ext_point_t
583 * A pointer to plug-in information containing this extension point.
584 * This reverse pointer is provided to make it easy to get information
585 * about the plug-in which is hosting a particular extension point.
587 cp_plugin_info_t *plugin;
590 * The local identifier uniquely identifying the extension point within the
591 * host plug-in. This corresponds to the @name id attribute of an
592 * @a extension-point element in a plug-in descriptor.
597 * The unique identifier of the extension point. This is automatically
598 * constructed by concatenating the identifier of the host plug-in and
599 * the local identifier of the extension point.
604 * An optional extension point name. NULL if not available. The extension
605 * point name is intended for display purposes only and the value can be
606 * localized. This corresponds to the @a name attribute of
607 * an @a extension-point element in a plug-in descriptor.
612 * An optional path to the extension schema definition.
613 * NULL if not available. The path is relative to the plug-in directory.
614 * This corresponds to the @a schema attribute
615 * of an @a extension-point element in a plug-in descriptor.
622 * Extension structure captures information about an extension. Extension
623 * structures are contained in @ref cp_plugin_info_t::extensions.
625 struct cp_extension_t
629 * A pointer to plug-in information containing this extension.
630 * This reverse pointer is provided to make it easy to get information
631 * about the plug-in which is hosting a particular extension.
633 cp_plugin_info_t *plugin;
636 * The unique identifier of the extension point this extension is
637 * attached to. This corresponds to the @a point attribute of an
638 * @a extension element in a plug-in descriptor.
643 * An optional local identifier uniquely identifying the extension within
644 * the host plug-in. NULL if not available. This corresponds to the
645 * @a id attribute of an @a extension element in a plug-in descriptor.
650 * An optional unique identifier of the extension. NULL if not available.
651 * This is automatically constructed by concatenating the identifier
652 * of the host plug-in and the local identifier of the extension.
657 * An optional extension name. NULL if not available. The extension name
658 * is intended for display purposes only and the value can be localized.
659 * This corresponds to the @a name attribute
660 * of an @a extension element in a plug-in descriptor.
665 * Extension configuration starting with the extension element.
666 * This includes extension configuration information as a tree of
667 * configuration elements. These correspond to the @a extension
668 * element and its contents in a plug-in descriptor.
670 cp_cfg_element_t *configuration;
675 * A configuration element contains configuration information for an
676 * extension. Utility functions ::cp_lookup_cfg_element and
677 * ::cp_lookup_cfg_value can be used for traversing the tree of
678 * configuration elements. Pointer to the root configuration element is
679 * stored at @ref cp_extension_t::configuration and others are contained as
680 * @ref cp_cfg_element_t::children "children" of parent elements.
682 struct cp_cfg_element_t
686 * The name of the configuration element. This corresponds to the name of
687 * the element in a plug-in descriptor.
691 /** Number of attribute name, value pairs in the @ref atts array. */
692 unsigned int num_atts;
695 * An array of pointers to alternating attribute names and values.
696 * Attribute values can be localized.
701 * An optional value of this configuration element. NULL if not available.
702 * The value can be localized. This corresponds to the
703 * text contents of the element in a plug-in descriptor.
707 /** A pointer to the parent element or NULL if this is a root element. */
708 cp_cfg_element_t *parent;
710 /** The index of this element among its siblings (0-based). */
713 /** Number of children in the @ref children array. */
714 unsigned int num_children;
717 * An array of @ref num_children childrens of this element. These
718 * correspond to child elements in a plug-in descriptor.
720 cp_cfg_element_t *children;
725 * Container for plug-in runtime information. A plug-in runtime defines a
726 * static instance of this structure to pass information to the plug-in
727 * framework. The plug-in framework then uses the information
728 * to create and control plug-in instances. The symbol pointing
729 * to the runtime information instance is named by the @a funcs
730 * attribute of the @a runtime element in a plug-in descriptor.
732 * The following graph displays how these functions are used to control the
733 * state of the plug-in instance.
736 * digraph lifecycle {
738 * node [shape=ellipse, fontname=Helvetica, fontsize=10];
739 * edge [fontname=Helvetica, fontsize=10];
740 * none [label="no instance"];
741 * inactive [label="inactive"];
742 * active [label="active"];
743 * none -> inactive [label="create", URL="\ref create"];
744 * inactive -> active [label="start", URL="\ref start"];
745 * active -> inactive [label="stop", URL="\ref stop"];
746 * inactive -> none [label="destroy", URL="\ref destroy"];
750 struct cp_plugin_runtime_t
754 * An initialization function called to create a new plug-in
755 * runtime instance. The initialization function initializes and
756 * returns an opaque plug-in instance data pointer which is then
757 * passed on to other control functions. This data pointer should
758 * be used to access plug-in instance specific data. For example,
759 * the context reference must be stored as part of plug-in instance
760 * data if the plug-in runtime needs it. On failure, the function
763 * C-pluff API functions must not be called from within a create
764 * function invocation and symbols from imported plug-ins must not be
765 * used because they may not available yet.
767 * @param ctx the plug-in context of the new plug-in instance
768 * @return an opaque pointer to plug-in instance data or NULL on failure
770 void *(*create)(cp_context_t *ctx);
773 * A start function called to start a plug-in instance.
774 * The start function must return zero (CP_OK) on success and non-zero
775 * on failure. If the start fails then the stop function (if any) is
776 * called to clean up plug-in state. @ref cFuncsInit "Library initialization",
777 * @ref cFuncsContext "plug-in context management" and
778 * @ref cFuncsPlugin "plug-in management" functions must not be
779 * called from within a start function invocation. The start function
780 * pointer can be NULL if the plug-in runtime does not have a start
783 * The start function implementation should set up plug-in and return
784 * promptly. If there is further work to be done then a plug-in can
785 * start a thread or register a run function using ::cp_run_function.
786 * Symbols from imported plug-ins are guaranteed to be available for
787 * the start function.
789 * @param data an opaque pointer to plug-in instance data
790 * @return non-zero on success, or zero on failure
792 int (*start)(void *data);
795 * A stop function called to stop a plugin instance.
796 * This function must cease all plug-in runtime activities.
797 * @ref cFuncsInit "Library initialization",
798 * @ref cFuncsContext "plug-in context management",
799 * @ref cFuncsPlugin "plug-in management"
800 * functions, ::cp_run_function and ::cp_resolve_symbol must not be called
801 * from within a stop function invocation. The stop function pointer can
802 * be NULL if the plug-in runtime does not have a stop function.
803 * It is guaranteed that no run functions registered by the plug-in are
804 * called simultaneously or after the call to the stop function.
806 * The stop function should release any external resources hold by
807 * the plug-in. Dynamically resolved symbols are automatically released
808 * and dynamically defined symbols and registered run functions are
809 * automatically unregistered after the call to stop function.
810 * Resolved external symbols are still available for the stop function
811 * and symbols provided by the plug-in should remain available
812 * after the call to stop function (although functionality might be
813 * limited). Final cleanup can be safely done in the destroy function.
815 * @param data an opaque pointer to plug-in instance data
817 void (*stop)(void *data);
820 * A destroy function called to destroy a plug-in instance.
821 * This function should release any plug-in instance data.
822 * The plug-in is stopped before this function is called.
823 * C-Pluff API functions must not be called from within a destroy
824 * function invocation and symbols from imported plug-ins must not be
825 * used because they may not be available anymore. Correspondingly,
826 * it is guaranteed that the symbols provided by the plug-in are not
827 * used by other plug-ins when destroy function has been called.
829 * @param data an opaque pointer to plug-in instance data
831 void (*destroy)(void *data);
838 /* ------------------------------------------------------------------------
839 * Function declarations
840 * ----------------------------------------------------------------------*/
843 * @defgroup cFuncs Functions
845 * C API functions. The C-Pluff C API functions and
846 * any data exposed by them are generally thread-safe if the library has been
847 * compiled with multi-threading support. The
848 * @ref cFuncsInit "framework initialization functions"
849 * are exceptions, they are not thread-safe.
853 * @defgroup cFuncsFrameworkInfo Framework information
856 * These functions can be used to query runtime information about the
857 * linked in C-Pluff implementation. They may be used by the main program or
858 * by a plug-in runtime.
863 * Returns the release version string of the linked in C-Pluff
866 * @return the C-Pluff release version string
868 CP_C_API const char *cp_get_version(void) CP_GCC_PURE;
871 * Returns the canonical host type associated with the linked in C-Pluff implementation.
872 * A multi-platform installation manager could use this information to
873 * determine what plug-in versions to install.
875 * @return the canonical host type
877 CP_C_API const char *cp_get_host_type(void) CP_GCC_PURE;
883 * @defgroup cFuncsInit Framework initialization
886 * These functions are used for framework initialization.
887 * They are intended to be used by the main program. These functions are
893 * Sets the fatal error handler called on non-recoverable errors. The default
894 * error handler prints the error message out to standard error and aborts
895 * the program. If the user specified error handler returns then the framework
896 * will abort the program. Setting NULL error handler will restore the default
897 * handler. This function is not thread-safe and it should be called
898 * before initializing the framework to catch all fatal errors.
900 * @param error_handler the fatal error handler
902 CP_C_API void cp_set_fatal_error_handler(cp_fatal_error_func_t error_handler);
905 * Initializes the plug-in framework. This function must be called
906 * by the main program before calling any other plug-in framework
907 * functions except @ref cFuncsFrameworkInfo "framework information" functions and
908 * ::cp_set_fatal_error_handler. This function may be
909 * called several times but it is not thread-safe. Library resources
910 * should be released by calling ::cp_destroy when the framework is
911 * not needed anymore.
913 * Additionally, to enable localization support, the main program should
914 * set the current locale using @code setlocale(LC_ALL, "") @endcode
915 * before calling this function.
917 * @return @ref CP_OK (zero) on success or error code on failure
919 CP_C_API cp_status_t cp_init(void);
922 * Destroys the plug-in framework and releases the resources used by it.
923 * The plug-in framework is only destroyed after this function has
924 * been called as many times as ::cp_init. This function is not
925 * thread-safe. Plug-in framework functions other than ::cp_init,
926 * ::cp_get_framework_info and ::cp_set_fatal_error_handler
927 * must not be called after the plug-in framework has been destroyed.
928 * All contexts are destroyed and all data references returned by the
929 * framework become invalid.
931 CP_C_API void cp_destroy(void);
937 * @defgroup cFuncsContext Plug-in context initialization
940 * These functions are used to manage plug-in contexts from the main
941 * program perspective. They are not intended to be used by a plug-in runtime.
942 * From the main program perspective a plug-in context is a container for
943 * installed plug-ins. There can be several plug-in context instances if there
944 * are several independent sets of plug-ins. However, different plug-in
945 * contexts are not very isolated from each other in practice because the
946 * global symbols exported by a plug-in runtime in one context are visible to
947 * all plug-ins in all context instances.
952 * Creates a new plug-in context which can be used as a container for plug-ins.
953 * Plug-ins are loaded and installed into a specific context. The main
954 * program may have more than one plug-in context but the plug-ins that
955 * interact with each other should be placed in the same context. The
956 * resources associated with the context are released by calling
957 * ::cp_destroy_context when the context is not needed anymore. Remaining
958 * contexts are automatically destroyed when the plug-in framework is
961 * @param status pointer to the location where status code is to be stored, or NULL
962 * @return the newly created plugin context, or NULL on failure
964 CP_C_API cp_context_t *cp_create_context(cp_status_t *status);
967 * Destroys the specified plug-in context and releases the associated resources.
968 * Stops and uninstalls all plug-ins in the context. The context must not be
969 * accessed after calling this function.
971 * @param ctx the context to be destroyed
973 CP_C_API void cp_destroy_context(cp_context_t *ctx) CP_GCC_NONNULL(1);
976 * Registers a plug-in collection with a plug-in context. A plug-in collection
977 * is a directory that has plug-ins as its immediate subdirectories. The
978 * plug-in context will scan the directory when ::cp_scan_plugins is called.
979 * Returns @ref CP_OK if the directory has already been registered. A plug-in
980 * collection can be unregistered using ::cp_unregister_pcollection or
981 * ::cp_unregister_pcollections.
983 * @param ctx the plug-in context
984 * @param dir the directory
985 * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if insufficient memory
987 CP_C_API cp_status_t cp_register_pcollection(cp_context_t *ctx, const char *dir) CP_GCC_NONNULL(1,
991 * Unregisters a previously registered plug-in collection from a
992 * plug-in context. Plug-ins already loaded from the collection are not
993 * affected. Does nothing if the directory has not been registered.
994 * Plug-in collections can be registered using ::cp_register_pcollection.
996 * @param ctx the plug-in context
997 * @param dir the previously registered directory
999 CP_C_API void cp_unregister_pcollection(cp_context_t *ctx, const char *dir) CP_GCC_NONNULL(1, 2);
1002 * Unregisters all plug-in collections from a plug-in context.
1003 * Plug-ins already loaded are not affected. Plug-in collections can
1004 * be registered using ::cp_register_pcollection.
1006 * @param ctx the plug-in context
1008 CP_C_API void cp_unregister_pcollections(cp_context_t *ctx) CP_GCC_NONNULL(1);
1014 * @defgroup cFuncsLogging Logging
1017 * These functions can be used to receive and emit log messages related
1018 * to a particular plug-in context. They can be used by the main program
1019 * or by a plug-in runtime.
1024 * Registers a logger with a plug-in context or updates the settings of a
1025 * registered logger. The logger will receive selected log messages.
1026 * If the specified logger is not yet known, a new logger registration
1027 * is made, otherwise the settings for the existing logger are updated.
1028 * The logger can be unregistered using ::cp_unregister_logger and it is
1029 * automatically unregistered when the registering plug-in is stopped or
1030 * when the context is destroyed.
1032 * @param ctx the plug-in context to log
1033 * @param logger the logger function to be called
1034 * @param user_data the user data pointer passed to the logger
1035 * @param min_severity the minimum severity of messages passed to logger
1036 * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if insufficient memory
1038 CP_C_API cp_status_t cp_register_logger(cp_context_t *ctx, cp_logger_func_t logger, void *user_data,
1039 cp_log_severity_t min_severity) CP_GCC_NONNULL(1, 2);
1042 * Removes a logger registration.
1044 * @param ctx the plug-in context
1045 * @param logger the logger function to be unregistered
1047 CP_C_API void cp_unregister_logger(cp_context_t *ctx, cp_logger_func_t logger) CP_GCC_NONNULL(1, 2);
1050 * Emits a new log message.
1052 * @param ctx the plug-in context
1053 * @param severity the severity of the event
1054 * @param msg the log message (possibly localized)
1056 CP_C_API void cp_log(cp_context_t *ctx, cp_log_severity_t severity,
1057 const char *msg) CP_GCC_NONNULL(1, 3);
1060 * Returns whether a message of the specified severity would get logged.
1062 * @param ctx the plug-in context
1063 * @param severity the target logging severity
1064 * @return whether a message of the specified severity would get logged
1066 CP_C_API int cp_is_logged(cp_context_t *ctx, cp_log_severity_t severity) CP_GCC_NONNULL(1);
1072 * @defgroup cFuncsPlugin Plug-in management
1075 * These functions can be used to manage plug-ins. They are intended to be
1076 * used by the main program.
1081 * Loads a plug-in descriptor from the specified plug-in installation
1082 * path and returns information about the plug-in. The plug-in descriptor
1083 * is validated during loading. Possible loading errors are reported via the
1084 * specified plug-in context. The plug-in is not installed to the context.
1085 * If operation fails or the descriptor
1086 * is invalid then NULL is returned. The caller must release the returned
1087 * information by calling ::cp_release_plugin_info when it does not
1088 * need the information anymore, typically after installing the plug-in.
1089 * The returned plug-in information must not be modified.
1091 * @param ctx the plug-in context
1092 * @param path the installation path of the plug-in
1093 * @param status a pointer to the location where status code is to be stored, or NULL
1094 * @return pointer to the information structure or NULL if error occurs
1096 CP_C_API cp_plugin_info_t *cp_load_plugin_descriptor(cp_context_t *ctx, const char *path,
1097 cp_status_t *status) CP_GCC_NONNULL(1, 2);
1100 * Installs the plug-in described by the specified plug-in information
1101 * structure to the specified plug-in context. The plug-in information
1102 * must have been loaded using ::cp_load_plugin_descriptor with the same
1104 * The installation fails on #CP_ERR_CONFLICT if the context already
1105 * has an installed plug-in with the same plug-in identifier. Installation
1106 * also fails if the plug-in tries to install an extension point which
1107 * conflicts with an already installed extension point.
1108 * The plug-in information must not be modified but it is safe to call
1109 * ::cp_release_plugin_info after the plug-in has been installed.
1111 * @param ctx the plug-in context
1112 * @param pi plug-in information structure
1113 * @return @ref CP_OK (zero) on success or an error code on failure
1115 CP_C_API cp_status_t cp_install_plugin(cp_context_t *ctx, cp_plugin_info_t *pi) CP_GCC_NONNULL(1,
1119 * Scans for plug-ins in the registered plug-in directories, installing
1120 * new plug-ins and upgrading installed plug-ins. This function can be used to
1121 * initially load the plug-ins and to later rescan for new plug-ins.
1123 * When several versions of the same plug-in is available the most recent
1124 * version will be installed. The upgrade behavior depends on the specified
1125 * @ref cScanFlags "flags". If #CP_SP_UPGRADE is set then upgrades to installed plug-ins are
1126 * allowed. The old version is unloaded and the new version installed instead.
1127 * If #CP_SP_STOP_ALL_ON_UPGRADE is set then all active plug-ins are stopped
1128 * if any plug-ins are to be upgraded. If #CP_SP_STOP_ALL_ON_INSTALL is set then
1129 * all active plug-ins are stopped if any plug-ins are to be installed or
1130 * upgraded. Finally, if #CP_SP_RESTART_ACTIVE is set all currently active
1131 * plug-ins will be restarted after the changes (if they were stopped).
1133 * When removing plug-in files from the plug-in directories, the
1134 * plug-ins to be removed must be first unloaded. Therefore this function
1135 * does not check for removed plug-ins.
1137 * @param ctx the plug-in context
1138 * @param flags the bitmask of flags
1139 * @return @ref CP_OK (zero) on success or an error code on failure
1141 CP_C_API cp_status_t cp_scan_plugins(cp_context_t *ctx, int flags) CP_GCC_NONNULL(1);
1144 * Starts a plug-in. Also starts any imported plug-ins. If the plug-in is
1145 * already starting then
1146 * this function blocks until the plug-in has started or failed to start.
1147 * If the plug-in is already active then this function returns immediately.
1148 * If the plug-in is stopping then this function blocks until the plug-in
1149 * has stopped and then starts the plug-in.
1151 * @param ctx the plug-in context
1152 * @param id identifier of the plug-in to be started
1153 * @return @ref CP_OK (zero) on success or an error code on failure
1155 CP_C_API cp_status_t cp_start_plugin(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1, 2);
1158 * Stops a plug-in. First stops any dependent plug-ins that are currently
1159 * active. Then stops the specified plug-in. If the plug-in is already
1160 * stopping then this function blocks until the plug-in has stopped. If the
1161 * plug-in is already stopped then this function returns immediately. If the
1162 * plug-in is starting then this function blocks until the plug-in has
1163 * started (or failed to start) and then stops the plug-in.
1165 * @param ctx the plug-in context
1166 * @param id identifier of the plug-in to be stopped
1167 * @return @ref CP_OK (zero) on success or @ref CP_ERR_UNKNOWN if unknown plug-in
1169 CP_C_API cp_status_t cp_stop_plugin(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1, 2);
1172 * Stops all active plug-ins.
1174 * @param ctx the plug-in context
1176 CP_C_API void cp_stop_plugins(cp_context_t *ctx) CP_GCC_NONNULL(1);
1179 * Uninstalls the specified plug-in. The plug-in is first stopped if it is active.
1180 * Then uninstalls the plug-in and any dependent plug-ins.
1182 * @param ctx the plug-in context
1183 * @param id identifier of the plug-in to be unloaded
1184 * @return @ref CP_OK (zero) on success or @ref CP_ERR_UNKNOWN if unknown plug-in
1186 CP_C_API cp_status_t cp_uninstall_plugin(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1, 2);
1189 * Uninstalls all plug-ins. All plug-ins are first stopped and then
1192 * @param ctx the plug-in context
1194 CP_C_API void cp_uninstall_plugins(cp_context_t *ctx) CP_GCC_NONNULL(1);
1200 * @defgroup cFuncsPluginInfo Plug-in and extension information
1203 * These functions can be used to query information about the installed
1204 * plug-ins, extension points and extensions or to listen for plug-in state
1205 * changes. They may be used by the main program or by a plug-in runtime.
1210 * Returns static information about the specified plug-in. The returned
1211 * information must not be modified and the caller must
1212 * release the information by calling ::cp_release_info when the
1213 * information is not needed anymore. When a plug-in runtime calls this
1214 * function it may pass NULL as the identifier to get information about the
1217 * @param ctx the plug-in context
1218 * @param id identifier of the plug-in to be examined or NULL for self
1219 * @param status a pointer to the location where status code is to be stored, or NULL
1220 * @return pointer to the information structure or NULL on failure
1222 CP_C_API cp_plugin_info_t *cp_get_plugin_info(cp_context_t *ctx, const char *id,
1223 cp_status_t *status) CP_GCC_NONNULL(1);
1226 * Returns static information about the installed plug-ins. The returned
1227 * information must not be modified and the caller must
1228 * release the information by calling ::cp_release_info when the
1229 * information is not needed anymore.
1231 * @param ctx the plug-in context
1232 * @param status a pointer to the location where status code is to be stored, or NULL
1233 * @param num a pointer to the location where the number of returned plug-ins is stored, or NULL
1234 * @return pointer to a NULL-terminated list of pointers to plug-in information
1235 * or NULL on failure
1237 CP_C_API cp_plugin_info_t **cp_get_plugins_info(cp_context_t *ctx, cp_status_t *status,
1238 int *num) CP_GCC_NONNULL(1);
1241 * Returns static information about the currently installed extension points.
1242 * The returned information must not be modified and the caller must
1243 * release the information by calling ::cp_release_info when the
1244 * information is not needed anymore.
1246 * @param ctx the plug-in context
1247 * @param status a pointer to the location where status code is to be stored, or NULL
1248 * @param num filled with the number of returned extension points, if non-NULL
1249 * @return pointer to a NULL-terminated list of pointers to extension point
1250 * information or NULL on failure
1252 CP_C_API cp_ext_point_t **cp_get_ext_points_info(cp_context_t *ctx, cp_status_t *status,
1253 int *num) CP_GCC_NONNULL(1);
1256 * Returns static information about the currently installed extension points.
1257 * The returned information must not be modified and the caller must
1258 * release the information by calling ::cp_release_info when the
1259 * information is not needed anymore.
1261 * @param ctx the plug-in context
1262 * @param extpt_id the extension point identifier or NULL for all extensions
1263 * @param status a pointer to the location where status code is to be stored, or NULL
1264 * @param num a pointer to the location where the number of returned extension points is to be stored, or NULL
1265 * @return pointer to a NULL-terminated list of pointers to extension
1266 * information or NULL on failure
1268 CP_C_API cp_extension_t **cp_get_extensions_info(cp_context_t *ctx, const char *extpt_id,
1269 cp_status_t *status, int *num) CP_GCC_NONNULL(1);
1272 * Releases a previously obtained reference counted information object. The
1273 * documentation for functions returning such information refers
1274 * to this function. The information must not be accessed after it has
1275 * been released. The framework uses reference counting to deallocate
1276 * the information when it is not in use anymore.
1278 * @param ctx the plug-in context
1279 * @param info the information to be released
1281 CP_C_API void cp_release_info(cp_context_t *ctx, void *info) CP_GCC_NONNULL(1, 2);
1284 * Returns the current state of the specified plug-in. Returns
1285 * #CP_PLUGIN_UNINSTALLED if the specified plug-in identifier is unknown.
1287 * @param ctx the plug-in context
1288 * @param id the plug-in identifier
1289 * @return the current state of the plug-in
1291 CP_C_API cp_plugin_state_t cp_get_plugin_state(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1,
1295 * Registers a plug-in listener with a plug-in context. The listener is called
1296 * synchronously immediately after a plug-in state change. There can be several
1297 * listeners registered with the same context. A plug-in listener can be
1298 * unregistered using ::cp_unregister_plistener and it is automatically
1299 * unregistered when the registering plug-in is stopped or when the context
1302 * @param ctx the plug-in context
1303 * @param listener the plug-in listener to be added
1304 * @param user_data user data pointer supplied to the listener
1305 * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if out of resources
1307 CP_C_API cp_status_t cp_register_plistener(cp_context_t *ctx, cp_plugin_listener_func_t listener,
1308 void *user_data) CP_GCC_NONNULL(1, 2);
1311 * Removes a plug-in listener from a plug-in context. Does nothing if the
1312 * specified listener was not registered.
1314 * @param ctx the plug-in context
1315 * @param listener the plug-in listener to be removed
1317 CP_C_API void cp_unregister_plistener(cp_context_t *ctx,
1318 cp_plugin_listener_func_t listener) CP_GCC_NONNULL(1, 2);
1321 * Traverses a configuration element tree and returns the specified element.
1322 * The target element is specified by a base element and a relative path from
1323 * the base element to the target element. The path includes element names
1324 * separated by slash '/'. Two dots ".." can be used to designate a parent
1325 * element. Returns NULL if the specified element does not exist. If there are
1326 * several subelements with the same name, this function chooses the first one
1327 * when traversing the tree.
1329 * @param base the base configuration element
1330 * @param path the path to the target element
1331 * @return the target element or NULL if nonexisting
1333 CP_C_API cp_cfg_element_t *cp_lookup_cfg_element(cp_cfg_element_t *base,
1334 const char *path) CP_GCC_PURE CP_GCC_NONNULL(1, 2);
1337 * Traverses a configuration element tree and returns the value of the
1338 * specified element or attribute. The target element or attribute is specified
1339 * by a base element and a relative path from the base element to the target
1340 * element or attributes. The path includes element names
1341 * separated by slash '/'. Two dots ".." can be used to designate a parent
1342 * element. The path may end with '@' followed by an attribute name
1343 * to select an attribute. Returns NULL if the specified element or attribute
1344 * does not exist or does not have a value. If there are several subelements
1345 * with the same name, this function chooses the first one when traversing the
1348 * @param base the base configuration element
1349 * @param path the path to the target element
1350 * @return the value of the target element or attribute or NULL
1352 CP_C_API char *cp_lookup_cfg_value(cp_cfg_element_t *base,
1353 const char *path) CP_GCC_PURE CP_GCC_NONNULL(1, 2);
1359 * @defgroup cFuncsPluginExec Plug-in execution
1362 * These functions support a plug-in controlled execution model. Started plug-ins can
1363 * use ::cp_run_function to register @ref cp_run_func_t "a run function" which is called when the
1364 * main program calls ::cp_run_plugins or ::cp_run_plugins_step. A run
1365 * function should do a finite chunk of work and then return telling whether
1366 * there is more work to be done. A run function is automatically unregistered
1367 * when the plug-in is stopped. Run functions make it possible for plug-ins
1368 * to control the flow of execution or they can be used as a coarse
1369 * way of task switching if there is no multi-threading support.
1371 * The C-Pluff distribution includes a generic main program, cpluff-loader,
1372 * which only acts as a plug-in loader. It loads and starts up the
1373 * specified plug-ins, passing any additional startup arguments to them and
1374 * then just calls run functions of the plug-ins. This
1375 * makes it is possible to put all the application specific logic in
1376 * plug-ins. Application does not necessarily need a main program of its own.
1378 * It is also safe, from framework perspective, to call these functions from
1379 * multiple threads. Run functions may then be executed in parallel threads.
1384 * Registers a new run function. The plug-in instance data pointer is given to
1385 * the run function as a parameter. The run function must return zero if it has
1386 * finished its work or non-zero if it should be called again later. The run
1387 * function is unregistered when it returns zero. Plug-in framework functions
1388 * stopping the registering plug-in must not be called from within a run
1389 * function. This function does nothing if the specified run
1390 * function is already registered for the calling plug-in instance.
1392 * @param ctx the plug-in context of the registering plug-in
1393 * @param runfunc the run function to be registered
1394 * @return @ref CP_OK (zero) on success or an error code on failure
1396 CP_C_API cp_status_t cp_run_function(cp_context_t *ctx, cp_run_func_t runfunc) CP_GCC_NONNULL(1, 2);
1399 * Runs the started plug-ins as long as there is something to run.
1400 * This function calls repeatedly run functions registered by started plug-ins
1401 * until there are no more active run functions. This function is normally
1402 * called by a thin main proram, a loader, which loads plug-ins, starts some
1403 * plug-ins and then passes control over to the started plug-ins.
1405 * @param ctx the plug-in context containing the plug-ins
1407 CP_C_API void cp_run_plugins(cp_context_t *ctx) CP_GCC_NONNULL(1);
1410 * Runs one registered run function. This function calls one
1411 * active run function registered by a started plug-in. When the run function
1412 * returns this function also returns and passes control back to the main
1413 * program. The return value can be used to determine whether there are any
1414 * active run functions left. This function does nothing if there are no active
1415 * registered run functions.
1417 * @param ctx the plug-in context containing the plug-ins
1418 * @return whether there are active run functions waiting to be run
1420 CP_C_API int cp_run_plugins_step(cp_context_t *ctx) CP_GCC_NONNULL(1);
1423 * Sets startup arguments for the specified plug-in context. Like for usual
1424 * C main functions, the first argument is expected to be the name of the
1425 * program being executed or an empty string and the argument array should be
1426 * terminated by NULL entry. If the main program is
1427 * about to pass startup arguments to plug-ins it should call this function
1428 * before starting any plug-ins in the context. The arguments are not copied
1429 * and the caller is responsible for keeping the argument data available once
1430 * the arguments have been set until the context is destroyed. Plug-ins can
1431 * access the startup arguments using ::cp_get_context_args.
1433 * @param ctx the plug-in context
1434 * @param argv a NULL-terminated array of arguments
1436 CP_C_API void cp_set_context_args(cp_context_t *ctx, char **argv) CP_GCC_NONNULL(1, 2);
1439 * Returns the startup arguments associated with the specified
1440 * plug-in context. This function is intended to be used by a plug-in runtime.
1441 * Startup arguments are set by the main program using ::cp_set_context_args.
1442 * The returned argument count is zero and the array pointer is NULL if no
1443 * arguments have been set.
1445 * @param ctx the plug-in context
1446 * @param argc a pointer to a location where the number of startup arguments is stored, or NULL for none
1447 * @return an argument array terminated by NULL or NULL if not set
1449 CP_C_API char **cp_get_context_args(cp_context_t *ctx, int *argc) CP_GCC_NONNULL(1);
1455 * @defgroup cFuncsSymbols Dynamic symbols
1458 * These functions can be used to dynamically access symbols exported by the
1459 * plug-ins. They are intended to be used by a plug-in runtime or by the main
1465 * Defines a context specific symbol. If a plug-in has symbols which have
1466 * a plug-in instance specific value then the plug-in should define those
1467 * symbols when it is started. The defined symbols are cleared
1468 * automatically when the plug-in instance is stopped. Symbols can not be
1471 * @param ctx the plug-in context
1472 * @param name the name of the symbol
1473 * @param ptr pointer value for the symbol
1474 * @return @ref CP_OK (zero) on success or a status code on failure
1476 CP_C_API cp_status_t cp_define_symbol(cp_context_t *ctx, const char *name,
1477 void *ptr) CP_GCC_NONNULL(1, 2, 3);
1480 * Resolves a symbol provided by the specified plug-in. The plug-in is started
1481 * automatically if it is not already active. The symbol may be context
1482 * specific or global. The framework first looks for a context specific
1483 * symbol and then falls back to resolving a global symbol exported by the
1484 * plug-in runtime library. The symbol can be released using
1485 * ::cp_release_symbol when it is not needed anymore. Pointers obtained from
1486 * this function must not be passed on to other plug-ins or the main
1489 * When a plug-in runtime calls this function the plug-in framework creates
1490 * a dynamic dependency from the symbol using plug-in to the symbol
1491 * defining plug-in. The symbol using plug-in is stopped automatically if the
1492 * symbol defining plug-in is about to be stopped. If the symbol using plug-in
1493 * does not explicitly release the symbol then it is automatically released
1494 * after a call to the stop function. It is not safe to refer to a dynamically
1495 * resolved symbol in the stop function except to release it using
1496 * ::cp_release_symbol.
1498 * When the main program calls this function it is the responsibility of the
1499 * main program to always release the symbol before the symbol defining plug-in
1500 * is stopped. It is a fatal error if the symbol is not released before the
1501 * symbol defining plug-in is stopped.
1503 * @param ctx the plug-in context
1504 * @param id the identifier of the symbol defining plug-in
1505 * @param name the name of the symbol
1506 * @param status a pointer to the location where the status code is to be stored, or NULL
1507 * @return the pointer associated with the symbol or NULL on failure
1509 CP_C_API void *cp_resolve_symbol(cp_context_t *ctx, const char *id, const char *name,
1510 cp_status_t *status) CP_GCC_NONNULL(1, 2, 3);
1513 * Releases a previously obtained symbol. The pointer must not be used after
1514 * the symbol has been released. The symbol is released
1515 * only after as many calls to this function as there have been for
1516 * ::cp_resolve_symbol for the same plug-in and symbol.
1518 * @param ctx the plug-in context
1519 * @param ptr the pointer associated with the symbol
1521 CP_C_API void cp_release_symbol(cp_context_t *ctx, const void *ptr) CP_GCC_NONNULL(1, 2);
1528 #endif /*__cplusplus*/
1530 #endif /*CPLUFF_H_*/