cpluff.h

Go to the documentation of this file.
00001 /*-------------------------------------------------------------------------
00002  * C-Pluff, a plug-in framework for C
00003  * Copyright 2007 Johannes Lehtinen
00004  * 
00005  * Permission is hereby granted, free of charge, to any person obtaining a
00006  * copy of this software and associated documentation files (the "Software"),
00007  * to deal in the Software without restriction, including without limitation
00008  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
00009  * and/or sell copies of the Software, and to permit persons to whom the
00010  * Software is furnished to do so, subject to the following conditions:
00011  *
00012  * The above copyright notice and this permission notice shall be included
00013  * in all copies or substantial portions of the Software.
00014  *
00015  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
00016  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00017  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00018  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
00019  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
00020  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
00021  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00022  *-----------------------------------------------------------------------*/
00023 
00024 /** @file 
00025  * C-Pluff C API header file.
00026  * The elements declared here constitute the C-Pluff C API. To use the
00027  * API include this file and link the main program and plug-in runtime
00028  * libraries with the C-Pluff C library. In addition to local declarations,
00029  * this file also includes cpluffdef.h header file for defines common to C
00030  * and C++ API.
00031  */
00032 
00033 #ifndef CPLUFF_H_
00034 #define CPLUFF_H_
00035 
00036 /**
00037  * @defgroup cDefines Defines
00038  * Preprocessor defines.
00039  */
00040  
00041 #include <cpluffdef.h>
00042 
00043 #ifdef __cplusplus
00044 extern "C" {
00045 #endif /*__cplusplus*/
00046 
00047 
00048 /* ------------------------------------------------------------------------
00049  * Defines
00050  * ----------------------------------------------------------------------*/
00051 
00052 /**
00053  * @def CP_C_API
00054  * @ingroup cDefines
00055  *
00056  * Marks a symbol declaration to be part of the C-Pluff C API.
00057  * This macro declares the symbol to be imported from the C-Pluff library.
00058  */
00059 
00060 #ifndef CP_C_API
00061 #define CP_C_API CP_IMPORT
00062 #endif
00063 
00064 
00065 /**
00066  * @defgroup cScanFlags Flags for plug-in scanning
00067  * @ingroup cDefines
00068  *
00069  * These constants can be orred together for the flags
00070  * parameter of ::cp_scan_plugins.
00071  */
00072 /*@{*/
00073 
00074 /** 
00075  * This flag enables upgrades of installed plug-ins by unloading
00076  * the old version and installing the new version.
00077  */
00078 #define CP_SP_UPGRADE 0x01
00079 
00080 /**
00081  * This flag causes all plug-ins to be stopped before any
00082  * plug-ins are to be upgraded.
00083  */
00084 #define CP_SP_STOP_ALL_ON_UPGRADE 0x02
00085 
00086 /**
00087  * This flag causes all plug-ins to be stopped before any
00088  * plugins are to be installed (also if new version is to be installed
00089  * as part of an upgrade).
00090  */
00091 #define CP_SP_STOP_ALL_ON_INSTALL 0x04
00092 
00093 /**
00094  * Setting this flag causes the currently active plug-ins to be restarted
00095  * after all changes to the plug-ins have been made (if they were stopped).
00096  */
00097 #define CP_SP_RESTART_ACTIVE 0x08
00098 
00099 /*@}*/
00100 
00101 
00102 /* ------------------------------------------------------------------------
00103  * Data types
00104  * ----------------------------------------------------------------------*/
00105 
00106 /**
00107  * @defgroup cEnums Enumerations
00108  * Constant value enumerations.
00109  */
00110 
00111 /**
00112  * @defgroup cTypedefs Typedefs
00113  * Typedefs of various kind.
00114  */
00115 
00116 /**
00117  * @defgroup cStructs Data structures
00118  * Data structure definitions.
00119  */
00120  
00121 
00122 /* Enumerations */
00123 
00124 /**
00125  * @ingroup cEnums
00126  *
00127  * An enumeration of status codes returned by API functions.
00128  * Most of the interface functions return a status code. The returned
00129  * status code either indicates successful completion of the operation
00130  * or some specific kind of error. Some functions do not return a status
00131  * code because they never fail.
00132  */
00133 enum cp_status_t {
00134 
00135         /**
00136          * Operation was performed successfully (equals to zero).
00137          * @showinitializer
00138          */
00139         CP_OK = 0,
00140 
00141         /** Not enough memory or other operating system resources available */
00142         CP_ERR_RESOURCE,
00143 
00144         /** The specified object is unknown to the framework */
00145         CP_ERR_UNKNOWN,
00146 
00147         /** An I/O error occurred */
00148         CP_ERR_IO,
00149 
00150         /** Malformed plug-in descriptor was encountered when loading a plug-in */
00151         CP_ERR_MALFORMED,
00152 
00153         /** Plug-in or symbol conflicts with another plug-in or symbol. */
00154         CP_ERR_CONFLICT,
00155 
00156         /** Plug-in dependencies could not be satisfied. */
00157         CP_ERR_DEPENDENCY,
00158 
00159         /** Plug-in runtime signaled an error. */
00160         CP_ERR_RUNTIME
00161         
00162 };
00163 
00164 /**
00165  * @ingroup cEnums
00166  * An enumeration of possible plug-in states. Plug-in states are controlled
00167  * by @ref cFuncsPlugin "plug-in management functions". Plug-in states can be
00168  * observed by @ref cp_register_plistener "registering" a
00169  * @ref cp_plugin_listener_func_t "plug-in listener function"
00170  * or by calling ::cp_get_plugin_state.
00171  *
00172  * @sa cp_plugin_listener_t
00173  * @sa cp_get_plugin_state
00174  */
00175 enum cp_plugin_state_t {
00176 
00177         /**
00178          * Plug-in is not installed. No plug-in information has been
00179          * loaded.
00180          */
00181         CP_PLUGIN_UNINSTALLED,
00182         
00183         /**
00184          * Plug-in is installed. At this stage the plug-in information has
00185          * been loaded but its dependencies to other plug-ins has not yet
00186          * been resolved. The plug-in runtime has not been loaded yet.
00187          * The extension points and extensions provided by the plug-in
00188          * have been registered.
00189          */
00190         CP_PLUGIN_INSTALLED,
00191         
00192         /**
00193          * Plug-in dependencies have been resolved. At this stage it has
00194          * been verified that the dependencies of the plug-in are satisfied
00195          * and the plug-in runtime has been loaded but it is not active
00196          * (it has not been started or it has been stopped).
00197          * Plug-in is resolved when a dependent plug-in is being
00198          * resolved or before the plug-in is started. Plug-in is put
00199          * back to installed stage if its dependencies are being
00200          * uninstalled.
00201          */
00202         CP_PLUGIN_RESOLVED,
00203         
00204         /**
00205          * Plug-in is starting. The plug-in has been resolved and the start
00206          * function (if any) of the plug-in runtime is about to be called.
00207          * A plug-in is started when explicitly requested by the main
00208          * program or when a dependent plug-in is about to be started or when
00209          * a dynamic symbol defined by the plug-in is being resolved. This state
00210          * is omitted and the state changes directly from resolved to active
00211          * if the plug-in runtime does not define a start function.
00212          */
00213         CP_PLUGIN_STARTING,
00214         
00215         /**
00216          * Plug-in is stopping. The stop function (if any) of the plug-in
00217          * runtime is about to be called. A plug-in is stopped if the start
00218          * function fails or when stopping is explicitly
00219          * requested by the main program or when its dependencies are being
00220          * stopped. This state is omitted and the state changes directly from
00221          * active to resolved if the plug-in runtime does not define a stop
00222          * function.
00223          */
00224         CP_PLUGIN_STOPPING,
00225         
00226         /**
00227          * Plug-in has been successfully started and it has not yet been
00228          * stopped.
00229          */
00230         CP_PLUGIN_ACTIVE
00231         
00232 };
00233 
00234 /**
00235  * @ingroup cEnums
00236  * An enumeration of possible message severities for framework logging. These
00237  * constants are used when passing a log message to a
00238  * @ref cp_logger_func_t "logger function" and when
00239  * @ref cp_register_logger "registering" a logger function.
00240  */
00241 enum cp_log_severity_t {
00242 
00243         /** Used for detailed debug messages */
00244         CP_LOG_DEBUG,
00245         
00246         /** Used for informational messages such as plug-in state changes */
00247         CP_LOG_INFO,
00248         
00249         /** Used for messages warning about possible problems */
00250         CP_LOG_WARNING,
00251         
00252         /** Used for messages reporting errors */
00253         CP_LOG_ERROR
00254         
00255 };
00256 
00257 /*@}*/
00258 
00259 
00260 /* Typedefs */
00261 
00262 /**
00263  * @defgroup cTypedefsOpaque Opaque types
00264  * @ingroup cTypedefs
00265  * Opaque data type definitions.
00266  */
00267 /*@{*/
00268  
00269 /**
00270  * A plug-in context represents the co-operation environment of a set of
00271  * plug-ins from the perspective of a particular participating plug-in or
00272  * the perspective of the main program. It is used as an opaque handle to
00273  * the shared resources but the framework also uses the context to identify
00274  * the plug-in or the main program invoking framework functions. Therefore
00275  * a plug-in should not generally expose its context instance to other
00276  * plug-ins or the main program and neither should the main program
00277  * expose its context instance to plug-ins. The main program creates
00278  * plug-in contexts using ::cp_create_context and plug-ins receive their
00279  * plug-in contexts via @ref cp_plugin_runtime_t::create.
00280  */
00281 typedef struct cp_context_t cp_context_t;
00282 
00283 /*@}*/
00284 
00285  /**
00286   * @defgroup cTypedefsShorthand Shorthand type names
00287   * @ingroup cTypedefs
00288   * Shorthand type names for structs and enumerations.
00289   */
00290 /*@{*/
00291 
00292 /** A type for cp_plugin_info_t structure. */
00293 typedef struct cp_plugin_info_t cp_plugin_info_t;
00294 
00295 /** A type for cp_plugin_import_t structure. */
00296 typedef struct cp_plugin_import_t cp_plugin_import_t;
00297 
00298 /** A type for cp_ext_point_t structure. */
00299 typedef struct cp_ext_point_t cp_ext_point_t;
00300 
00301 /** A type for cp_extension_t structure. */
00302 typedef struct cp_extension_t cp_extension_t;
00303 
00304 /** A type for cp_cfg_element_t structure. */
00305 typedef struct cp_cfg_element_t cp_cfg_element_t;
00306 
00307 /** A type for cp_plugin_runtime_t structure. */
00308 typedef struct cp_plugin_runtime_t cp_plugin_runtime_t;
00309 
00310 /** A type for cp_status_t enumeration. */
00311 typedef enum cp_status_t cp_status_t;
00312 
00313 /** A type for cp_plugin_state_t enumeration. */
00314 typedef enum cp_plugin_state_t cp_plugin_state_t;
00315 
00316 /** A type for cp_log_severity_t enumeration. */
00317 typedef enum cp_log_severity_t cp_log_severity_t;
00318 
00319 /*@}*/
00320 
00321 /**
00322  * @defgroup cTypedefsFuncs Callback function types
00323  * @ingroup cTypedefs
00324  * Typedefs for client supplied callback functions.
00325  */
00326 /*@{*/
00327 
00328 /**
00329  * A listener function called synchronously after a plugin state change.
00330  * The function should return promptly.
00331  * @ref cFuncsInit "Library initialization",
00332  * @ref cFuncsContext "plug-in context management",
00333  * @ref cFuncsPlugin "plug-in management",
00334  * listener registration (::cp_register_plistener and ::cp_unregister_plistener)
00335  * and @ref cFuncsSymbols "dynamic symbol" functions must not be called from
00336  * within a plug-in listener invocation. Listener functions are registered
00337  * using ::cp_register_plistener.
00338  * 
00339  * @param plugin_id the plug-in identifier
00340  * @param old_state the old plug-in state
00341  * @param new_state the new plug-in state
00342  * @param user_data the user data pointer supplied at listener registration
00343  */
00344 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);
00345 
00346 /**
00347  * A logger function called to log selected plug-in framework messages. The
00348  * messages may be localized. Plug-in framework API functions must not
00349  * be called from within a logger function invocation. In a multi-threaded
00350  * environment logger function invocations are serialized by the framework.
00351  * Logger functions are registered using ::cp_register_logger.
00352  *
00353  * @param severity the severity of the message
00354  * @param msg the message to be logged, possibly localized
00355  * @param apid the identifier of the activating plug-in or NULL for the main program
00356  * @param user_data the user data pointer given when the logger was registered
00357  */
00358 typedef void (*cp_logger_func_t)(cp_log_severity_t severity, const char *msg, const char *apid, void *user_data);
00359 
00360 /**
00361  * A fatal error handler for handling unrecoverable errors. If the error
00362  * handler returns then the framework aborts the program. Plug-in framework
00363  * API functions must not be called from within a fatal error handler
00364  * invocation. The fatal error handler function is set using
00365  * ::cp_set_fatal_error_handler.
00366  *
00367  * @param msg the possibly localized error message
00368  */
00369 typedef void (*cp_fatal_error_func_t)(const char *msg);
00370 
00371 /**
00372  * A run function registered by a plug-in to perform work.
00373  * The run function  should perform a finite chunk of work and it should
00374  * return a non-zero value if there is more work to be done. Run functions
00375  * are registered using ::cp_run_function and the usage is discussed in
00376  * more detail in the @ref cFuncsPluginExec "serial execution" section.
00377  * 
00378  * @param plugin_data the plug-in instance data pointer
00379  * @return non-zero if there is more work to be done or zero if finished
00380  */
00381 typedef int (*cp_run_func_t)(void *plugin_data);
00382 
00383 /*@}*/
00384 
00385 
00386 /* Data structures */
00387 
00388 /**
00389  * @ingroup cStructs
00390  * Plug-in information structure captures information about a plug-in. This
00391  * information can be loaded from a plug-in descriptor using
00392  * ::cp_load_plugin_descriptor. Information about installed plug-ins can
00393  * be obtained using ::cp_get_plugin_info and ::cp_get_plugins_info. This
00394  * structure corresponds to the @a plugin element in a plug-in descriptor.
00395  */
00396 struct cp_plugin_info_t {
00397         
00398         /**
00399          * The obligatory unique identifier of the plugin. A recommended way
00400          * to generate identifiers is to use domain name service (DNS) prefixes
00401          * (for example, org.cpluff.ExamplePlugin) to avoid naming conflicts. This
00402          * corresponds to the @a id attribute of the @a plugin element in a plug-in
00403          * descriptor.
00404          */
00405         char *identifier;
00406         
00407         /**
00408          * An optional plug-in name. NULL if not available. The plug-in name is
00409          * intended only for display purposes and the value can be localized.
00410          * This corresponds to the @a name attribute of the @a plugin element in
00411          * a plug-in descriptor.
00412          */
00413         char *name;
00414         
00415         /**
00416          * An optional release version string. NULL if not available. This
00417          * corresponds to the @a version attribute of the @a plugin element in
00418          * a plug-in descriptor.
00419          */
00420         char *version;
00421         
00422         /**
00423          * An optional provider name. NULL if not available. This is the name of
00424          * the author or the organization providing the plug-in. The
00425          * provider name is intended only for display purposes and the value can
00426          * be localized. This corresponds to the @a provider-name attribute of the
00427          * @a plugin element in a plug-in descriptor.
00428          */
00429         char *provider_name;
00430         
00431         /**
00432          * Path of the plugin directory or NULL if not known. This is the
00433          * (absolute or relative) path to the plug-in directory containing
00434          * plug-in data and the plug-in runtime library. The value corresponds
00435          * to the path specified to ::cp_load_plugin_descriptor when loading
00436          * the plug-in.
00437          */
00438         char *plugin_path;
00439         
00440         /**
00441          * Optional ABI compatibility information. NULL if not available.
00442          * This is the earliest version of the plug-in interface the current
00443          * interface is backwards compatible with when it comes to the application
00444          * binary interface (ABI) of the plug-in. That is, plug-in clients compiled against
00445          * any plug-in interface version from @a abi_bw_compatibility to
00446          * @ref version (inclusive) can use the current version of the plug-in
00447          * binary. This describes binary or runtime compatibility.
00448          * The value corresponds to the @a abi-compatibility
00449          * attribute of the @a backwards-compatibility element in a plug-in descriptor.
00450          */
00451         char *abi_bw_compatibility;
00452         
00453         /**
00454          * Optional API compatibility information. NULL if not available.
00455          * This is the earliest version of the plug-in interface the current
00456          * interface is backwards compatible with when it comes to the
00457          * application programming interface (API) of the plug-in. That is,
00458          * plug-in clients written for any plug-in interface version from
00459          * @a api_bw_compatibility to @ref version (inclusive) can be compiled
00460          * against the current version of the plug-in API. This describes
00461          * source or build time compatibility. The value corresponds to the
00462          * @a api-compatibility attribute of the @a backwards-compatibility
00463          * element in a plug-in descriptor. 
00464          */
00465         char *api_bw_compatibility;
00466         
00467         /**
00468          * Optional C-Pluff version requirement. NULL if not available.
00469          * This is the version of the C-Pluff implementation the plug-in was
00470          * compiled against. It is used to determine the compatibility of
00471          * the plug-in runtime and the linked in C-Pluff implementation. Any
00472          * C-Pluff version that is backwards compatible on binary level with the
00473          * specified version fulfills the requirement.
00474          */
00475         char *req_cpluff_version;
00476         
00477         /** Number of import entries in the @ref imports array. */
00478         unsigned int num_imports;
00479         
00480         /**
00481          * An array of @ref num_imports import entries. These correspond to
00482          * @a import elements in a plug-in descriptor.
00483          */
00484         cp_plugin_import_t *imports;
00485 
00486     /**
00487      * The base name of the plug-in runtime library, or NULL if none.
00488      * A platform specific prefix (for example, "lib") and an extension
00489      * (for example, ".dll" or ".so") may be added to the base name.
00490      * This corresponds to the @a library attribute of the
00491      * @a runtime element in a plug-in descriptor.
00492      */
00493     char *runtime_lib_name;
00494     
00495     /**
00496      * The symbol pointing to the plug-in runtime function information or
00497      * NULL if none. The symbol with this name should point to an instance of
00498      * @ref cp_plugin_runtime_t structure. This corresponds to the
00499      * @a funcs attribute of the @a runtime element in a plug-in descriptor. 
00500      */
00501     char *runtime_funcs_symbol;
00502     
00503         /** Number of extension points in @ref ext_points array. */
00504         unsigned int num_ext_points;
00505         
00506         /**
00507          * An array of @ref num_ext_points extension points provided by this
00508          * plug-in. These correspond to @a extension-point elements in a
00509          * plug-in descriptor.
00510          */
00511         cp_ext_point_t *ext_points;
00512         
00513         /** Number of extensions in @ref extensions array. */
00514         unsigned int num_extensions;
00515         
00516         /**
00517          * An array of @ref num_extensions extensions provided by this
00518          * plug-in. These correspond to @a extension elements in a plug-in
00519          * descriptor.
00520          */
00521         cp_extension_t *extensions;
00522 
00523 };
00524 
00525 /**
00526  * @ingroup cStructs
00527  * Information about plug-in import. Plug-in import structures are
00528  * contained in @ref cp_plugin_info_t::imports.
00529  */
00530 struct cp_plugin_import_t {
00531         
00532         /**
00533          * The identifier of the imported plug-in. This corresponds to the
00534          * @a plugin attribute of the @a import element in a plug-in descriptor.
00535          */
00536         char *plugin_id;
00537         
00538         /**
00539          * An optional version requirement. NULL if no version requirement.
00540          * This is the version of the imported plug-in the importing plug-in was
00541          * compiled against. Any version of the imported plug-in that is
00542          * backwards compatible with this version fulfills the requirement.
00543          * This corresponds to the @a if-version attribute of the @a import
00544          * element in a plug-in descriptor.
00545          */
00546         char *version;
00547         
00548         /**
00549          * Is this import optional. 1 for optional and 0 for mandatory import.
00550          * An optional import causes the imported plug-in to be started if it is
00551          * available but does not stop the importing plug-in from starting if the
00552          * imported plug-in is not available. If the imported plug-in is available
00553          * but the API version conflicts with the API version requirement then the
00554          * importing plug-in fails to start. This corresponds to the @a optional
00555          * attribute of the @a import element in a plug-in descriptor.
00556          */
00557         int optional;
00558 };
00559 
00560 /**
00561  * @ingroup cStructs
00562  * Extension point structure captures information about an extension
00563  * point. Extension point structures are contained in
00564  * @ref cp_plugin_info_t::ext_points.
00565  */
00566 struct cp_ext_point_t {
00567 
00568         /**
00569          * A pointer to plug-in information containing this extension point.
00570          * This reverse pointer is provided to make it easy to get information
00571          * about the plug-in which is hosting a particular extension point.
00572          */
00573         cp_plugin_info_t *plugin;
00574         
00575         /**
00576          * The local identifier uniquely identifying the extension point within the
00577          * host plug-in. This corresponds to the @name id attribute of an
00578          * @a extension-point element in a plug-in descriptor.
00579          */
00580         char *local_id;
00581         
00582         /**
00583          * The unique identifier of the extension point. This is automatically
00584          * constructed by concatenating the identifier of the host plug-in and
00585          * the local identifier of the extension point.
00586          */
00587         char *identifier;
00588 
00589         /**
00590          * An optional extension point name. NULL if not available. The extension
00591          * point name is intended for display purposes only and the value can be
00592          * localized. This corresponds to the @a name attribute of
00593          * an @a extension-point element in a plug-in descriptor.
00594          */
00595         char *name;
00596         
00597         /**
00598          * An optional path to the extension schema definition.
00599          * NULL if not available. The path is relative to the plug-in directory.
00600          * This corresponds to the @a schema attribute
00601          * of an @a extension-point element in a plug-in descriptor.
00602          */
00603         char *schema_path;
00604 };
00605 
00606 /**
00607  * @ingroup cStructs
00608  * Extension structure captures information about an extension. Extension
00609  * structures are contained in @ref cp_plugin_info_t::extensions.
00610  */
00611 struct cp_extension_t {
00612 
00613         /** 
00614          * A pointer to plug-in information containing this extension.
00615          * This reverse pointer is provided to make it easy to get information
00616          * about the plug-in which is hosting a particular extension.
00617          */
00618         cp_plugin_info_t *plugin;
00619         
00620         /**
00621          * The unique identifier of the extension point this extension is
00622          * attached to. This corresponds to the @a point attribute of an
00623          * @a extension element in a plug-in descriptor.
00624          */
00625         char *ext_point_id;
00626         
00627         /**
00628          * An optional local identifier uniquely identifying the extension within
00629          * the host plug-in. NULL if not available. This corresponds to the
00630          * @a id attribute of an @a extension element in a plug-in descriptor.
00631          */
00632         char *local_id;
00633 
00634     /**
00635      * An optional unique identifier of the extension. NULL if not available.
00636      * This is automatically constructed by concatenating the identifier
00637      * of the host plug-in and the local identifier of the extension.
00638      */
00639     char *identifier;
00640          
00641         /** 
00642          * An optional extension name. NULL if not available. The extension name
00643          * is intended for display purposes only and the value can be localized.
00644          * This corresponds to the @a name attribute
00645          * of an @a extension element in a plug-in descriptor.
00646          **/
00647         char *name;
00648         
00649         /**
00650          * Extension configuration starting with the extension element.
00651          * This includes extension configuration information as a tree of
00652          * configuration elements. These correspond to the @a extension
00653          * element and its contents in a plug-in descriptor.
00654          */
00655         cp_cfg_element_t *configuration;
00656 };
00657 
00658 /**
00659  * @ingroup cStructs
00660  * A configuration element contains configuration information for an
00661  * extension. Utility functions ::cp_lookup_cfg_element and
00662  * ::cp_lookup_cfg_value can be used for traversing the tree of
00663  * configuration elements. Pointer to the root configuration element is
00664  * stored at @ref cp_extension_t::configuration and others are contained as
00665  * @ref cp_cfg_element_t::children "children" of parent elements.
00666  */
00667 struct cp_cfg_element_t {
00668         
00669         /**
00670          * The name of the configuration element. This corresponds to the name of
00671          * the element in a plug-in descriptor.
00672          */
00673         char *name;
00674 
00675         /** Number of attribute name, value pairs in the @ref atts array. */
00676         unsigned int num_atts;
00677         
00678         /**
00679          * An array of pointers to alternating attribute names and values.
00680          * Attribute values can be localized.
00681          */
00682         char **atts;
00683         
00684         /**
00685           * An optional value of this configuration element. NULL if not available.
00686           * The value can be localized. This corresponds to the
00687           * text contents of the element in a plug-in descriptor.
00688           */
00689         char *value;
00690         
00691         /** A pointer to the parent element or NULL if this is a root element. */
00692         cp_cfg_element_t *parent;
00693         
00694         /** The index of this element among its siblings (0-based). */
00695         unsigned int index;
00696         
00697         /** Number of children in the @ref children array. */
00698         unsigned int num_children;
00699 
00700         /**
00701          * An array of @ref num_children childrens of this element. These
00702          * correspond to child elements in a plug-in descriptor.
00703          */
00704         cp_cfg_element_t *children;
00705 };
00706 
00707 /**
00708  * @ingroup cStructs
00709  * Container for plug-in runtime information. A plug-in runtime defines a
00710  * static instance of this structure to pass information to the plug-in
00711  * framework. The plug-in framework then uses the information
00712  * to create and control plug-in instances. The symbol pointing
00713  * to the runtime information instance is named by the @a funcs
00714  * attribute of the @a runtime element in a plug-in descriptor.
00715  * 
00716  * The following graph displays how these functions are used to control the
00717  * state of the plug-in instance. 
00718  * 
00719  * @dot
00720  * digraph lifecycle {
00721  *   rankdir=LR;
00722  *   node [shape=ellipse, fontname=Helvetica, fontsize=10];
00723  *   edge [fontname=Helvetica, fontsize=10];
00724  *   none [label="no instance"];
00725  *   inactive [label="inactive"];
00726  *   active [label="active"];
00727  *   none -> inactive [label="create", URL="\ref create"];
00728  *   inactive -> active [label="start", URL="\ref start"];
00729  *   active -> inactive [label="stop", URL="\ref stop"];
00730  *   inactive -> none [label="destroy", URL="\ref destroy"];
00731  * }
00732  * @enddot
00733  */
00734 struct cp_plugin_runtime_t {
00735 
00736         /**
00737          * An initialization function called to create a new plug-in
00738          * runtime instance. The initialization function initializes and
00739          * returns an opaque plug-in instance data pointer which is then
00740          * passed on to other control functions. This data pointer should
00741          * be used to access plug-in instance specific data. For example,
00742          * the context reference must be stored as part of plug-in instance
00743          * data if the plug-in runtime needs it. On failure, the function
00744          * must return NULL.
00745          * 
00746          * C-pluff API functions must not be called from within a create
00747          * function invocation and symbols from imported plug-ins must not be
00748          * used because they may not available yet.
00749          * 
00750          * @param ctx the plug-in context of the new plug-in instance
00751          * @return an opaque pointer to plug-in instance data or NULL on failure
00752          */  
00753         void *(*create)(cp_context_t *ctx);
00754 
00755         /**
00756          * A start function called to start a plug-in instance.
00757          * The start function must return zero (CP_OK) on success and non-zero
00758          * on failure. If the start fails then the stop function (if any) is
00759          * called to clean up plug-in state. @ref cFuncsInit "Library initialization",
00760          * @ref cFuncsContext "plug-in context management" and
00761          * @ref cFuncsPlugin "plug-in management" functions must not be
00762          * called from within a start function invocation. The start function
00763          * pointer can be NULL if the plug-in runtime does not have a start
00764          * function.
00765          * 
00766          * The start function implementation should set up plug-in and return
00767          * promptly. If there is further work to be done then a plug-in can
00768          * start a thread or register a run function using ::cp_run_function.
00769          * Symbols from imported plug-ins are guaranteed to be available for
00770          * the start function.
00771          * 
00772          * @param data an opaque pointer to plug-in instance data
00773          * @return non-zero on success, or zero on failure
00774          */
00775         int (*start)(void *data);
00776         
00777         /**
00778          * A stop function called to stop a plugin instance.
00779          * This function must cease all plug-in runtime activities.
00780          * @ref cFuncsInit "Library initialization",
00781          * @ref cFuncsContext "plug-in context management",
00782          * @ref cFuncsPlugin "plug-in management"
00783          * functions, ::cp_run_function and ::cp_resolve_symbol must not be called
00784          * from within a stop function invocation. The stop function pointer can
00785          * be NULL if the plug-in runtime does not have a stop function.
00786          * It is guaranteed that no run functions registered by the plug-in are
00787          * called simultaneously or after the call to the stop function.
00788          * 
00789          * The stop function should release any external resources hold by
00790          * the plug-in. Dynamically resolved symbols are automatically released
00791          * and dynamically defined symbols and registered run functions are
00792          * automatically unregistered after the call to stop function.
00793          * Resolved external symbols are still available for the stop function
00794          * and symbols provided by the plug-in should remain available
00795          * after the call to stop function (although functionality might be
00796          * limited). Final cleanup can be safely done in the destroy function.
00797          *
00798          * @param data an opaque pointer to plug-in instance data
00799          */
00800         void (*stop)(void *data);
00801 
00802         /**
00803          * A destroy function called to destroy a plug-in instance.
00804          * This function should release any plug-in instance data.
00805          * The plug-in is stopped before this function is called.
00806          * C-Pluff API functions must not be called from within a destroy
00807          * function invocation and symbols from imported plug-ins must not be
00808          * used because they may not be available anymore. Correspondingly,
00809          * it is guaranteed that the symbols provided by the plug-in are not
00810          * used by other plug-ins when destroy function has been called.
00811          *
00812          * @param data an opaque pointer to plug-in instance data
00813          */
00814         void (*destroy)(void *data);
00815 
00816 };
00817 
00818 /*@}*/
00819 
00820 
00821 /* ------------------------------------------------------------------------
00822  * Function declarations
00823  * ----------------------------------------------------------------------*/
00824 
00825 /**
00826  * @defgroup cFuncs Functions
00827  *
00828  * C API functions. The C-Pluff C API functions and
00829  * any data exposed by them are generally thread-safe if the library has been
00830  * compiled with multi-threading support. The
00831  * @ref cFuncsInit "framework initialization functions"
00832  * are exceptions, they are not thread-safe.
00833  */
00834 
00835 /**
00836  * @defgroup cFuncsFrameworkInfo Framework information
00837  * @ingroup cFuncs
00838  *
00839  * These functions can be used to query runtime information about the
00840  * linked in C-Pluff implementation. They may be used by the main program or
00841  * by a plug-in runtime.
00842  */
00843 /*@{*/
00844 
00845 /**
00846  * Returns the release version string of the linked in C-Pluff
00847  * implementation.
00848  * 
00849  * @return the C-Pluff release version string
00850  */
00851 CP_C_API const char *cp_get_version(void) CP_GCC_PURE;
00852 
00853 /**
00854  * Returns the canonical host type associated with the linked in C-Pluff implementation.
00855  * A multi-platform installation manager could use this information to
00856  * determine what plug-in versions to install.
00857  * 
00858  * @return the canonical host type
00859  */
00860 CP_C_API const char *cp_get_host_type(void) CP_GCC_PURE;
00861 
00862 /*@}*/
00863 
00864 
00865 /**
00866  * @defgroup cFuncsInit Framework initialization
00867  * @ingroup cFuncs
00868  *
00869  * These functions are used for framework initialization.
00870  * They are intended to be used by the main program. These functions are
00871  * not thread safe.
00872  */
00873 /*@{*/
00874 
00875 /**
00876  * Sets the fatal error handler called on non-recoverable errors. The default
00877  * error handler prints the error message out to standard error and aborts
00878  * the program. If the user specified error handler returns then the framework
00879  * will abort the program. Setting NULL error handler will restore the default
00880  * handler. This function is not thread-safe and it should be called
00881  * before initializing the framework to catch all fatal errors.
00882  * 
00883  * @param error_handler the fatal error handler
00884  */
00885 CP_C_API void cp_set_fatal_error_handler(cp_fatal_error_func_t error_handler);
00886 
00887 /**
00888  * Initializes the plug-in framework. This function must be called
00889  * by the main program before calling any other plug-in framework
00890  * functions except @ref cFuncsFrameworkInfo "framework information" functions and
00891  * ::cp_set_fatal_error_handler. This function may be
00892  * called several times but it is not thread-safe. Library resources
00893  * should be released by calling ::cp_destroy when the framework is
00894  * not needed anymore.
00895  *
00896  * Additionally, to enable localization support, the main program should
00897  * set the current locale using @code setlocale(LC_ALL, "") @endcode
00898  * before calling this function.
00899  *
00900  * @return @ref CP_OK (zero) on success or error code on failure
00901  */
00902 CP_C_API cp_status_t cp_init(void);
00903 
00904 /**
00905  * Destroys the plug-in framework and releases the resources used by it.
00906  * The plug-in framework is only destroyed after this function has
00907  * been called as many times as ::cp_init. This function is not
00908  * thread-safe. Plug-in framework functions other than ::cp_init,
00909  * ::cp_get_framework_info and ::cp_set_fatal_error_handler
00910  * must not be called after the plug-in framework has been destroyed.
00911  * All contexts are destroyed and all data references returned by the
00912  * framework become invalid.
00913  */
00914 CP_C_API void cp_destroy(void);
00915 
00916 /*@}*/
00917 
00918 
00919 /**
00920  * @defgroup cFuncsContext Plug-in context initialization
00921  * @ingroup cFuncs
00922  *
00923  * These functions are used to manage plug-in contexts from the main
00924  * program perspective. They are not intended to be used by a plug-in runtime.
00925  * From the main program perspective a plug-in context is a container for
00926  * installed plug-ins. There can be several plug-in context instances if there
00927  * are several independent sets of plug-ins. However, different plug-in
00928  * contexts are not very isolated from each other in practice because the
00929  * global symbols exported by a plug-in runtime in one context are visible to
00930  * all plug-ins in all context instances.
00931  */
00932 /*@{*/
00933 
00934 /**
00935  * Creates a new plug-in context which can be used as a container for plug-ins.
00936  * Plug-ins are loaded and installed into a specific context. The main
00937  * program may have more than one plug-in context but the plug-ins that
00938  * interact with each other should be placed in the same context. The
00939  * resources associated with the context are released by calling
00940  * ::cp_destroy_context when the context is not needed anymore. Remaining
00941  * contexts are automatically destroyed when the plug-in framework is
00942  * destroyed. 
00943  * 
00944  * @param status pointer to the location where status code is to be stored, or NULL
00945  * @return the newly created plugin context, or NULL on failure
00946  */
00947 CP_C_API cp_context_t * cp_create_context(cp_status_t *status);
00948 
00949 /**
00950  * Destroys the specified plug-in context and releases the associated resources.
00951  * Stops and uninstalls all plug-ins in the context. The context must not be
00952  * accessed after calling this function.
00953  * 
00954  * @param ctx the context to be destroyed
00955  */
00956 CP_C_API void cp_destroy_context(cp_context_t *ctx) CP_GCC_NONNULL(1);
00957 
00958 /**
00959  * Registers a plug-in collection with a plug-in context. A plug-in collection
00960  * is a directory that has plug-ins as its immediate subdirectories. The
00961  * plug-in context will scan the directory when ::cp_scan_plugins is called.
00962  * Returns @ref CP_OK if the directory has already been registered. A plug-in
00963  * collection can be unregistered using ::cp_unregister_pcollection or
00964  * ::cp_unregister_pcollections.
00965  * 
00966  * @param ctx the plug-in context
00967  * @param dir the directory
00968  * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if insufficient memory
00969  */
00970 CP_C_API cp_status_t cp_register_pcollection(cp_context_t *ctx, const char *dir) CP_GCC_NONNULL(1, 2);
00971 
00972 /**
00973  * Unregisters a previously registered plug-in collection from a
00974  * plug-in context. Plug-ins already loaded from the collection are not
00975  * affected. Does nothing if the directory has not been registered.
00976  * Plug-in collections can be registered using ::cp_register_pcollection.
00977  * 
00978  * @param ctx the plug-in context
00979  * @param dir the previously registered directory
00980  */
00981 CP_C_API void cp_unregister_pcollection(cp_context_t *ctx, const char *dir) CP_GCC_NONNULL(1, 2);
00982 
00983 /**
00984  * Unregisters all plug-in collections from a plug-in context.
00985  * Plug-ins already loaded are not affected. Plug-in collections can
00986  * be registered using ::cp_register_pcollection.
00987  * 
00988  * @param ctx the plug-in context
00989  */
00990 CP_C_API void cp_unregister_pcollections(cp_context_t *ctx) CP_GCC_NONNULL(1);
00991 
00992 /*@}*/
00993 
00994 
00995 /**
00996  * @defgroup cFuncsLogging Logging
00997  * @ingroup cFuncs
00998  *
00999  * These functions can be used to receive and emit log messages related
01000  * to a particular plug-in context. They can be used by the main program
01001  * or by a plug-in runtime.
01002  */
01003 /*@{*/
01004 
01005 /**
01006  * Registers a logger with a plug-in context or updates the settings of a
01007  * registered logger. The logger will receive selected log messages.
01008  * If the specified logger is not yet known, a new logger registration
01009  * is made, otherwise the settings for the existing logger are updated.
01010  * The logger can be unregistered using ::cp_unregister_logger and it is
01011  * automatically unregistered when the registering plug-in is stopped or
01012  * when the context is destroyed. 
01013  *
01014  * @param ctx the plug-in context to log
01015  * @param logger the logger function to be called
01016  * @param user_data the user data pointer passed to the logger
01017  * @param min_severity the minimum severity of messages passed to logger
01018  * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if insufficient memory
01019  */
01020 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);
01021 
01022 /**
01023  * Removes a logger registration.
01024  *
01025  * @param ctx the plug-in context
01026  * @param logger the logger function to be unregistered
01027  */
01028 CP_C_API void cp_unregister_logger(cp_context_t *ctx, cp_logger_func_t logger) CP_GCC_NONNULL(1, 2);
01029 
01030 /**
01031  * Emits a new log message.
01032  * 
01033  * @param ctx the plug-in context
01034  * @param severity the severity of the event
01035  * @param msg the log message (possibly localized)
01036  */
01037 CP_C_API void cp_log(cp_context_t *ctx, cp_log_severity_t severity, const char *msg) CP_GCC_NONNULL(1, 3);
01038 
01039 /**
01040  * Returns whether a message of the specified severity would get logged.
01041  * 
01042  * @param ctx the plug-in context
01043  * @param severity the target logging severity
01044  * @return whether a message of the specified severity would get logged
01045  */
01046 CP_C_API int cp_is_logged(cp_context_t *ctx, cp_log_severity_t severity) CP_GCC_NONNULL(1);
01047 
01048 /*@}*/
01049 
01050 
01051 /**
01052  * @defgroup cFuncsPlugin Plug-in management
01053  * @ingroup cFuncs
01054  *
01055  * These functions can be used to manage plug-ins. They are intended to be
01056  * used by the main program.
01057  */
01058 /*@{*/
01059 
01060 /**
01061  * Loads a plug-in descriptor from the specified plug-in installation
01062  * path and returns information about the plug-in. The plug-in descriptor
01063  * is validated during loading. Possible loading errors are reported via the
01064  * specified plug-in context. The plug-in is not installed to the context.
01065  * If operation fails or the descriptor
01066  * is invalid then NULL is returned. The caller must release the returned
01067  * information by calling ::cp_release_plugin_info when it does not
01068  * need the information anymore, typically after installing the plug-in.
01069  * The returned plug-in information must not be modified.
01070  * 
01071  * @param ctx the plug-in context
01072  * @param path the installation path of the plug-in
01073  * @param status a pointer to the location where status code is to be stored, or NULL
01074  * @return pointer to the information structure or NULL if error occurs
01075  */
01076 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);
01077 
01078 /**
01079  * Installs the plug-in described by the specified plug-in information
01080  * structure to the specified plug-in context. The plug-in information
01081  * must have been loaded using ::cp_load_plugin_descriptor with the same
01082  * plug-in context.
01083  * The installation fails on #CP_ERR_CONFLICT if the context already
01084  * has an installed plug-in with the same plug-in identifier. Installation
01085  * also fails if the plug-in tries to install an extension point which
01086  * conflicts with an already installed extension point.
01087  * The plug-in information must not be modified but it is safe to call
01088  * ::cp_release_plugin_info after the plug-in has been installed.
01089  *
01090  * @param ctx the plug-in context
01091  * @param pi plug-in information structure
01092  * @return @ref CP_OK (zero) on success or an error code on failure
01093  */
01094 CP_C_API cp_status_t cp_install_plugin(cp_context_t *ctx, cp_plugin_info_t *pi) CP_GCC_NONNULL(1, 2);
01095 
01096 /**
01097  * Scans for plug-ins in the registered plug-in directories, installing
01098  * new plug-ins and upgrading installed plug-ins. This function can be used to
01099  * initially load the plug-ins and to later rescan for new plug-ins.
01100  * 
01101  * When several versions of the same plug-in is available the most recent
01102  * version will be installed. The upgrade behavior depends on the specified
01103  * @ref cScanFlags "flags". If #CP_SP_UPGRADE is set then upgrades to installed plug-ins are
01104  * allowed. The old version is unloaded and the new version installed instead.
01105  * If #CP_SP_STOP_ALL_ON_UPGRADE is set then all active plug-ins are stopped
01106  * if any plug-ins are to be upgraded. If #CP_SP_STOP_ALL_ON_INSTALL is set then
01107  * all active plug-ins are stopped if any plug-ins are to be installed or
01108  * upgraded. Finally, if #CP_SP_RESTART_ACTIVE is set all currently active
01109  * plug-ins will be restarted after the changes (if they were stopped).
01110  * 
01111  * When removing plug-in files from the plug-in directories, the
01112  * plug-ins to be removed must be first unloaded. Therefore this function
01113  * does not check for removed plug-ins.
01114  * 
01115  * @param ctx the plug-in context
01116  * @param flags the bitmask of flags
01117  * @return @ref CP_OK (zero) on success or an error code on failure
01118  */
01119 CP_C_API cp_status_t cp_scan_plugins(cp_context_t *ctx, int flags) CP_GCC_NONNULL(1);
01120 
01121 /**
01122  * Starts a plug-in. Also starts any imported plug-ins. If the plug-in is
01123  * already starting then
01124  * this function blocks until the plug-in has started or failed to start.
01125  * If the plug-in is already active then this function returns immediately.
01126  * If the plug-in is stopping then this function blocks until the plug-in
01127  * has stopped and then starts the plug-in.
01128  * 
01129  * @param ctx the plug-in context
01130  * @param id identifier of the plug-in to be started
01131  * @return @ref CP_OK (zero) on success or an error code on failure
01132  */
01133 CP_C_API cp_status_t cp_start_plugin(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1, 2);
01134 
01135 /**
01136  * Stops a plug-in. First stops any dependent plug-ins that are currently
01137  * active. Then stops the specified plug-in. If the plug-in is already
01138  * stopping then this function blocks until the plug-in has stopped. If the
01139  * plug-in is already stopped then this function returns immediately. If the
01140  * plug-in is starting then this function blocks until the plug-in has
01141  * started (or failed to start) and then stops the plug-in.
01142  * 
01143  * @param ctx the plug-in context
01144  * @param id identifier of the plug-in to be stopped
01145  * @return @ref CP_OK (zero) on success or @ref CP_ERR_UNKNOWN if unknown plug-in
01146  */
01147 CP_C_API cp_status_t cp_stop_plugin(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1, 2);
01148 
01149 /**
01150  * Stops all active plug-ins.
01151  * 
01152  * @param ctx the plug-in context
01153  */
01154 CP_C_API void cp_stop_plugins(cp_context_t *ctx) CP_GCC_NONNULL(1);
01155 
01156 /**
01157  * Uninstalls the specified plug-in. The plug-in is first stopped if it is active.
01158  * Then uninstalls the plug-in and any dependent plug-ins.
01159  * 
01160  * @param ctx the plug-in context
01161  * @param id identifier of the plug-in to be unloaded
01162  * @return @ref CP_OK (zero) on success or @ref CP_ERR_UNKNOWN if unknown plug-in
01163  */
01164 CP_C_API cp_status_t cp_uninstall_plugin(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1, 2);
01165 
01166 /**
01167  * Uninstalls all plug-ins. All plug-ins are first stopped and then
01168  * uninstalled.
01169  * 
01170  * @param ctx the plug-in context
01171  */
01172 CP_C_API void cp_uninstall_plugins(cp_context_t *ctx) CP_GCC_NONNULL(1);
01173 
01174 /*@}*/
01175 
01176 
01177 /**
01178  * @defgroup cFuncsPluginInfo Plug-in and extension information
01179  * @ingroup cFuncs
01180  *
01181  * These functions can be used to query information about the installed
01182  * plug-ins, extension points and extensions or to listen for plug-in state
01183  * changes. They may be used by the main program or by a plug-in runtime.
01184  */
01185 /*@{*/
01186 
01187 /**
01188  * Returns static information about the specified plug-in. The returned
01189  * information must not be modified and the caller must
01190  * release the information by calling ::cp_release_info when the
01191  * information is not needed anymore. When a plug-in runtime calls this
01192  * function it may pass NULL as the identifier to get information about the
01193  * plug-in itself.
01194  * 
01195  * @param ctx the plug-in context
01196  * @param id identifier of the plug-in to be examined or NULL for self
01197  * @param status a pointer to the location where status code is to be stored, or NULL
01198  * @return pointer to the information structure or NULL on failure
01199  */
01200 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);
01201 
01202 /**
01203  * Returns static information about the installed plug-ins. The returned
01204  * information must not be modified and the caller must
01205  * release the information by calling ::cp_release_info when the
01206  * information is not needed anymore.
01207  * 
01208  * @param ctx the plug-in context
01209  * @param status a pointer to the location where status code is to be stored, or NULL
01210  * @param num a pointer to the location where the number of returned plug-ins is stored, or NULL
01211  * @return pointer to a NULL-terminated list of pointers to plug-in information
01212  *                      or NULL on failure
01213  */
01214 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);
01215 
01216 /**
01217  * Returns static information about the currently installed extension points.
01218  * The returned information must not be modified and the caller must
01219  * release the information by calling ::cp_release_info when the
01220  * information is not needed anymore.
01221  *
01222  * @param ctx the plug-in context
01223  * @param status a pointer to the location where status code is to be stored, or NULL
01224  * @param num filled with the number of returned extension points, if non-NULL
01225  * @return pointer to a NULL-terminated list of pointers to extension point
01226  *                      information or NULL on failure
01227  */
01228 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);
01229 
01230 /**
01231  * Returns static information about the currently installed extension points.
01232  * The returned information must not be modified and the caller must
01233  * release the information by calling ::cp_release_info when the
01234  * information is not needed anymore.
01235  *
01236  * @param ctx the plug-in context
01237  * @param extpt_id the extension point identifier or NULL for all extensions
01238  * @param status a pointer to the location where status code is to be stored, or NULL
01239  * @param num a pointer to the location where the number of returned extension points is to be stored, or NULL
01240  * @return pointer to a NULL-terminated list of pointers to extension
01241  *                      information or NULL on failure
01242  */
01243 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);
01244 
01245 /**
01246  * Releases a previously obtained reference counted information object. The
01247  * documentation for functions returning such information refers
01248  * to this function. The information must not be accessed after it has
01249  * been released. The framework uses reference counting to deallocate
01250  * the information when it is not in use anymore.
01251  * 
01252  * @param ctx the plug-in context
01253  * @param info the information to be released
01254  */
01255 CP_C_API void cp_release_info(cp_context_t *ctx, void *info) CP_GCC_NONNULL(1, 2);
01256 
01257 /**
01258  * Returns the current state of the specified plug-in. Returns
01259  * #CP_PLUGIN_UNINSTALLED if the specified plug-in identifier is unknown.
01260  * 
01261  * @param ctx the plug-in context
01262  * @param id the plug-in identifier
01263  * @return the current state of the plug-in
01264  */
01265 CP_C_API cp_plugin_state_t cp_get_plugin_state(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1, 2);
01266 
01267 /**
01268  * Registers a plug-in listener with a plug-in context. The listener is called
01269  * synchronously immediately after a plug-in state change. There can be several
01270  * listeners registered with the same context. A plug-in listener can be
01271  * unregistered using ::cp_unregister_plistener and it is automatically
01272  * unregistered when the registering plug-in is stopped or when the context
01273  * is destroyed.
01274  * 
01275  * @param ctx the plug-in context
01276  * @param listener the plug-in listener to be added
01277  * @param user_data user data pointer supplied to the listener
01278  * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if out of resources
01279  */
01280 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);
01281 
01282 /**
01283  * Removes a plug-in listener from a plug-in context. Does nothing if the
01284  * specified listener was not registered.
01285  * 
01286  * @param ctx the plug-in context
01287  * @param listener the plug-in listener to be removed
01288  */
01289 CP_C_API void cp_unregister_plistener(cp_context_t *ctx, cp_plugin_listener_func_t listener) CP_GCC_NONNULL(1, 2);
01290 
01291 /**
01292  * Traverses a configuration element tree and returns the specified element.
01293  * The target element is specified by a base element and a relative path from
01294  * the base element to the target element. The path includes element names
01295  * separated by slash '/'. Two dots ".." can be used to designate a parent
01296  * element. Returns NULL if the specified element does not exist. If there are
01297  * several subelements with the same name, this function chooses the first one
01298  * when traversing the tree.
01299  *
01300  * @param base the base configuration element
01301  * @param path the path to the target element
01302  * @return the target element or NULL if nonexisting
01303  */
01304 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);
01305 
01306 /**
01307  * Traverses a configuration element tree and returns the value of the
01308  * specified element or attribute. The target element or attribute is specified
01309  * by a base element and a relative path from the base element to the target
01310  * element or attributes. The path includes element names
01311  * separated by slash '/'. Two dots ".." can be used to designate a parent
01312  * element. The path may end with '@' followed by an attribute name
01313  * to select an attribute. Returns NULL if the specified element or attribute
01314  * does not exist or does not have a value. If there are several subelements
01315  * with the same name, this function chooses the first one when traversing the
01316  * tree.
01317  *
01318  * @param base the base configuration element
01319  * @param path the path to the target element
01320  * @return the value of the target element or attribute or NULL
01321  */
01322 CP_C_API char * cp_lookup_cfg_value(cp_cfg_element_t *base, const char *path) CP_GCC_PURE CP_GCC_NONNULL(1, 2);
01323 
01324 /*@}*/
01325 
01326 
01327 /**
01328  * @defgroup cFuncsPluginExec Plug-in execution
01329  * @ingroup cFuncs
01330  *
01331  * These functions support a plug-in controlled execution model. Started plug-ins can
01332  * use ::cp_run_function to register @ref cp_run_func_t "a run function" which is called when the
01333  * main program calls ::cp_run_plugins or ::cp_run_plugins_step. A run
01334  * function should do a finite chunk of work and then return telling whether
01335  * there is more work to be done. A run function is automatically unregistered
01336  * when the plug-in is stopped. Run functions make it possible for plug-ins
01337  * to control the flow of execution or they can be used as a coarse
01338  * way of task switching if there is no multi-threading support.
01339  *
01340  * The C-Pluff distribution includes a generic main program, cpluff-loader,
01341  * which only acts as a plug-in loader. It loads and starts up the
01342  * specified plug-ins, passing any additional startup arguments to them and
01343  * then just calls run functions of the plug-ins. This
01344  * makes it is possible to put all the application specific logic in
01345  * plug-ins. Application does not necessarily need a main program of its own.
01346  * 
01347  * It is also safe, from framework perspective, to call these functions from
01348  * multiple threads. Run functions may then be executed in parallel threads.
01349  */
01350 /*@{*/
01351 
01352 /**
01353  * Registers a new run function. The plug-in instance data pointer is given to
01354  * the run function as a parameter. The run function must return zero if it has
01355  * finished its work or non-zero if it should be called again later. The run
01356  * function is unregistered when it returns zero. Plug-in framework functions
01357  * stopping the registering plug-in must not be called from within a run
01358  * function. This function does nothing if the specified run
01359  * function is already registered for the calling plug-in instance.
01360  * 
01361  * @param ctx the plug-in context of the registering plug-in
01362  * @param runfunc the run function to be registered
01363  * @return @ref CP_OK (zero) on success or an error code on failure
01364  */
01365 CP_C_API cp_status_t cp_run_function(cp_context_t *ctx, cp_run_func_t runfunc) CP_GCC_NONNULL(1, 2);
01366 
01367 /**
01368  * Runs the started plug-ins as long as there is something to run.
01369  * This function calls repeatedly run functions registered by started plug-ins
01370  * until there are no more active run functions. This function is normally
01371  * called by a thin main proram, a loader, which loads plug-ins, starts some
01372  * plug-ins and then passes control over to the started plug-ins.
01373  * 
01374  * @param ctx the plug-in context containing the plug-ins
01375  */
01376 CP_C_API void cp_run_plugins(cp_context_t *ctx) CP_GCC_NONNULL(1);
01377 
01378 /**
01379  * Runs one registered run function. This function calls one
01380  * active run function registered by a started plug-in. When the run function
01381  * returns this function also returns and passes control back to the main
01382  * program. The return value can be used to determine whether there are any
01383  * active run functions left. This function does nothing if there are no active
01384  * registered run functions.
01385  * 
01386  * @param ctx the plug-in context containing the plug-ins
01387  * @return whether there are active run functions waiting to be run
01388  */
01389 CP_C_API int cp_run_plugins_step(cp_context_t *ctx) CP_GCC_NONNULL(1);
01390 
01391 /**
01392  * Sets startup arguments for the specified plug-in context. Like for usual
01393  * C main functions, the first argument is expected to be the name of the
01394  * program being executed or an empty string and the argument array should be
01395  * terminated by NULL entry. If the main program is
01396  * about to pass startup arguments to plug-ins it should call this function
01397  * before starting any plug-ins in the context. The arguments are not copied
01398  * and the caller is responsible for keeping the argument data available once
01399  * the arguments have been set until the context is destroyed. Plug-ins can
01400  * access the startup arguments using ::cp_get_context_args.
01401  * 
01402  * @param ctx the plug-in context
01403  * @param argv a NULL-terminated array of arguments
01404  */
01405 CP_C_API void cp_set_context_args(cp_context_t *ctx, char **argv) CP_GCC_NONNULL(1, 2);
01406 
01407 /**
01408  * Returns the startup arguments associated with the specified
01409  * plug-in context. This function is intended to be used by a plug-in runtime.
01410  * Startup arguments are set by the main program using ::cp_set_context_args.
01411  * The returned argument count is zero and the array pointer is NULL if no
01412  * arguments have been set.
01413  * 
01414  * @param ctx the plug-in context
01415  * @param argc a pointer to a location where the number of startup arguments is stored, or NULL for none
01416  * @return an argument array terminated by NULL or NULL if not set
01417  */
01418 CP_C_API char **cp_get_context_args(cp_context_t *ctx, int *argc) CP_GCC_NONNULL(1);
01419 
01420 /*@}*/
01421 
01422 
01423 /**
01424  * @defgroup cFuncsSymbols Dynamic symbols
01425  * @ingroup cFuncs
01426  *
01427  * These functions can be used to dynamically access symbols exported by the
01428  * plug-ins. They are intended to be used by a plug-in runtime or by the main
01429  * program. 
01430  */
01431 /*@{*/
01432 
01433 /**
01434  * Defines a context specific symbol. If a plug-in has symbols which have
01435  * a plug-in instance specific value then the plug-in should define those
01436  * symbols when it is started. The defined symbols are cleared
01437  * automatically when the plug-in instance is stopped. Symbols can not be
01438  * redefined.
01439  * 
01440  * @param ctx the plug-in context
01441  * @param name the name of the symbol
01442  * @param ptr pointer value for the symbol
01443  * @return @ref CP_OK (zero) on success or a status code on failure
01444  */
01445 CP_C_API cp_status_t cp_define_symbol(cp_context_t *ctx, const char *name, void *ptr) CP_GCC_NONNULL(1, 2, 3);
01446 
01447 /**
01448  * Resolves a symbol provided by the specified plug-in. The plug-in is started
01449  * automatically if it is not already active. The symbol may be context
01450  * specific or global. The framework first looks for a context specific
01451  * symbol and then falls back to resolving a global symbol exported by the
01452  * plug-in runtime library. The symbol can be released using
01453  * ::cp_release_symbol when it is not needed anymore. Pointers obtained from
01454  * this function must not be passed on to other plug-ins or the main
01455  * program.
01456  * 
01457  * When a plug-in runtime calls this function the plug-in framework creates
01458  * a dynamic dependency from the symbol using plug-in to the symbol
01459  * defining plug-in. The symbol using plug-in is stopped automatically if the
01460  * symbol defining plug-in is about to be stopped. If the symbol using plug-in
01461  * does not explicitly release the symbol then it is automatically released
01462  * after a call to the stop function. It is not safe to refer to a dynamically
01463  * resolved symbol in the stop function except to release it using
01464  * ::cp_release_symbol.
01465  * 
01466  * When the main program calls this function it is the responsibility of the
01467  * main program to always release the symbol before the symbol defining plug-in
01468  * is stopped. It is a fatal error if the symbol is not released before the
01469  * symbol defining plug-in is stopped.
01470  *
01471  * @param ctx the plug-in context
01472  * @param id the identifier of the symbol defining plug-in
01473  * @param name the name of the symbol
01474  * @param status a pointer to the location where the status code is to be stored, or NULL
01475  * @return the pointer associated with the symbol or NULL on failure
01476  */
01477 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);
01478 
01479 /**
01480  * Releases a previously obtained symbol. The pointer must not be used after
01481  * the symbol has been released. The symbol is released
01482  * only after as many calls to this function as there have been for
01483  * ::cp_resolve_symbol for the same plug-in and symbol.
01484  *
01485  * @param ctx the plug-in context
01486  * @param ptr the pointer associated with the symbol
01487  */
01488 CP_C_API void cp_release_symbol(cp_context_t *ctx, const void *ptr) CP_GCC_NONNULL(1, 2);
01489 
01490 /*@}*/
01491 
01492 
01493 #ifdef __cplusplus
01494 }
01495 #endif /*__cplusplus*/
01496 
01497 #endif /*CPLUFF_H_*/

Generated on Thu Jun 7 05:13:36 2007 for C-Pluff C API by doxygen 1.5.1