cpluff.h

Go to the documentation of this file.

/*-------------------------------------------------------------------------
 * C-Pluff, a plug-in framework for C
 * Copyright 2007 Johannes Lehtinen
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *-----------------------------------------------------------------------*/

/** @file 
 * C-Pluff C API header file.
 * The elements declared here constitute the C-Pluff C API. To use the
 * API include this file and link the main program and plug-in runtime
 * libraries with the C-Pluff C library. In addition to local declarations,
 * this file also includes cpluffdef.h header file for defines common to C
 * and C++ API.
 */

#ifndef CPLUFF_H_
#define CPLUFF_H_

/**
 * @defgroup cDefines Defines
 * Preprocessor defines.
 */
 
#include <cpluffdef.h>

#ifdef __cplusplus
extern "C" {
#endif /*__cplusplus*/


/* ------------------------------------------------------------------------
 * Defines
 * ----------------------------------------------------------------------*/

/**
 * @def CP_C_API
 * @ingroup cDefines
 *
 * Marks a symbol declaration to be part of the C-Pluff C API.
 * This macro declares the symbol to be imported from the C-Pluff library.
 */

#ifndef CP_C_API
#define CP_C_API CP_IMPORT
#endif


/**
 * @defgroup cScanFlags Flags for plug-in scanning
 * @ingroup cDefines
 *
 * These constants can be orred together for the flags
 * parameter of ::cp_scan_plugins.
 */
/*@{*/

/** 
 * This flag enables upgrades of installed plug-ins by unloading
 * the old version and installing the new version.
 */
#define CP_SP_UPGRADE 0x01

/**
 * This flag causes all plug-ins to be stopped before any
 * plug-ins are to be upgraded.
 */
#define CP_SP_STOP_ALL_ON_UPGRADE 0x02

/**
 * This flag causes all plug-ins to be stopped before any
 * plugins are to be installed (also if new version is to be installed
 * as part of an upgrade).
 */
#define CP_SP_STOP_ALL_ON_INSTALL 0x04

/**
 * Setting this flag causes the currently active plug-ins to be restarted
 * after all changes to the plug-ins have been made (if they were stopped).
 */
#define CP_SP_RESTART_ACTIVE 0x08

/*@}*/


/* ------------------------------------------------------------------------
 * Data types
 * ----------------------------------------------------------------------*/

/**
 * @defgroup cEnums Enumerations
 * Constant value enumerations.
 */

/**
 * @defgroup cTypedefs Typedefs
 * Typedefs of various kind.
 */

/**
 * @defgroup cStructs Data structures
 * Data structure definitions.
 */
 

/* Enumerations */

/**
 * @ingroup cEnums
 *
 * An enumeration of status codes returned by API functions.
 * Most of the interface functions return a status code. The returned
 * status code either indicates successful completion of the operation
 * or some specific kind of error. Some functions do not return a status
 * code because they never fail.
 */
enum cp_status_t {

        /**
         * Operation was performed successfully (equals to zero).
         * @showinitializer
         */
        CP_OK = 0,

        /** Not enough memory or other operating system resources available */
        CP_ERR_RESOURCE,

        /** The specified object is unknown to the framework */
        CP_ERR_UNKNOWN,

        /** An I/O error occurred */
        CP_ERR_IO,

        /** Malformed plug-in descriptor was encountered when loading a plug-in */
        CP_ERR_MALFORMED,

        /** Plug-in or symbol conflicts with another plug-in or symbol. */
        CP_ERR_CONFLICT,

        /** Plug-in dependencies could not be satisfied. */
        CP_ERR_DEPENDENCY,

        /** Plug-in runtime signaled an error. */
        CP_ERR_RUNTIME
        
};

/**
 * @ingroup cEnums
 * An enumeration of possible plug-in states. Plug-in states are controlled
 * by @ref cFuncsPlugin "plug-in management functions". Plug-in states can be
 * observed by @ref cp_register_plistener "registering" a
 * @ref cp_plugin_listener_func_t "plug-in listener function"
 * or by calling ::cp_get_plugin_state.
 *
 * @sa cp_plugin_listener_t
 * @sa cp_get_plugin_state
 */
enum cp_plugin_state_t {

        /**
         * Plug-in is not installed. No plug-in information has been
         * loaded.
         */
        CP_PLUGIN_UNINSTALLED,
        
        /**
         * Plug-in is installed. At this stage the plug-in information has
         * been loaded but its dependencies to other plug-ins has not yet
         * been resolved. The plug-in runtime has not been loaded yet.
         * The extension points and extensions provided by the plug-in
         * have been registered.
         */
        CP_PLUGIN_INSTALLED,
        
        /**
         * Plug-in dependencies have been resolved. At this stage it has
         * been verified that the dependencies of the plug-in are satisfied
         * and the plug-in runtime has been loaded but it is not active
         * (it has not been started or it has been stopped).
         * Plug-in is resolved when a dependent plug-in is being
         * resolved or before the plug-in is started. Plug-in is put
         * back to installed stage if its dependencies are being
         * uninstalled.
         */
        CP_PLUGIN_RESOLVED,
        
        /**
         * Plug-in is starting. The plug-in has been resolved and the start
         * function (if any) of the plug-in runtime is about to be called.
         * A plug-in is started when explicitly requested by the main
         * program or when a dependent plug-in is about to be started or when
         * a dynamic symbol defined by the plug-in is being resolved. This state
         * is omitted and the state changes directly from resolved to active
         * if the plug-in runtime does not define a start function.
         */
        CP_PLUGIN_STARTING,
        
        /**
         * Plug-in is stopping. The stop function (if any) of the plug-in
         * runtime is about to be called. A plug-in is stopped if the start
         * function fails or when stopping is explicitly
         * requested by the main program or when its dependencies are being
         * stopped. This state is omitted and the state changes directly from
         * active to resolved if the plug-in runtime does not define a stop
         * function.
         */
        CP_PLUGIN_STOPPING,
        
        /**
         * Plug-in has been successfully started and it has not yet been
         * stopped.
         */
        CP_PLUGIN_ACTIVE
        
};

/**
 * @ingroup cEnums
 * An enumeration of possible message severities for framework logging. These
 * constants are used when passing a log message to a
 * @ref cp_logger_func_t "logger function" and when
 * @ref cp_register_logger "registering" a logger function.
 */
enum cp_log_severity_t {

        /** Used for detailed debug messages */
        CP_LOG_DEBUG,
        
        /** Used for informational messages such as plug-in state changes */
        CP_LOG_INFO,
        
        /** Used for messages warning about possible problems */
        CP_LOG_WARNING,
        
        /** Used for messages reporting errors */
        CP_LOG_ERROR
        
};

/*@}*/


/* Typedefs */

/**
 * @defgroup cTypedefsOpaque Opaque types
 * @ingroup cTypedefs
 * Opaque data type definitions.
 */
/*@{*/
 
/**
 * A plug-in context represents the co-operation environment of a set of
 * plug-ins from the perspective of a particular participating plug-in or
 * the perspective of the main program. It is used as an opaque handle to
 * the shared resources but the framework also uses the context to identify
 * the plug-in or the main program invoking framework functions. Therefore
 * a plug-in should not generally expose its context instance to other
 * plug-ins or the main program and neither should the main program
 * expose its context instance to plug-ins. The main program creates
 * plug-in contexts using ::cp_create_context and plug-ins receive their
 * plug-in contexts via @ref cp_plugin_runtime_t::create.
 */
typedef struct cp_context_t cp_context_t;

/*@}*/

 /**
  * @defgroup cTypedefsShorthand Shorthand type names
  * @ingroup cTypedefs
  * Shorthand type names for structs and enumerations.
  */
/*@{*/

/** A type for cp_plugin_info_t structure. */
typedef struct cp_plugin_info_t cp_plugin_info_t;

/** A type for cp_plugin_import_t structure. */
typedef struct cp_plugin_import_t cp_plugin_import_t;

/** A type for cp_ext_point_t structure. */
typedef struct cp_ext_point_t cp_ext_point_t;

/** A type for cp_extension_t structure. */
typedef struct cp_extension_t cp_extension_t;

/** A type for cp_cfg_element_t structure. */
typedef struct cp_cfg_element_t cp_cfg_element_t;

/** A type for cp_plugin_runtime_t structure. */
typedef struct cp_plugin_runtime_t cp_plugin_runtime_t;

/** A type for cp_plugin_loader_t structure. */
typedef struct cp_plugin_loader_t cp_plugin_loader_t;

/** A type for cp_status_t enumeration. */
typedef enum cp_status_t cp_status_t;

/** A type for cp_plugin_state_t enumeration. */
typedef enum cp_plugin_state_t cp_plugin_state_t;

/** A type for cp_log_severity_t enumeration. */
typedef enum cp_log_severity_t cp_log_severity_t;

/*@}*/

/**
 * @defgroup cTypedefsFuncs Callback function types
 * @ingroup cTypedefs
 * Typedefs for client supplied callback functions.
 */
/*@{*/

/**
 * A listener function called synchronously after a plugin state change.
 * The function should return promptly.
 * @ref cFuncsInit "Library initialization",
 * @ref cFuncsContext "plug-in context management",
 * @ref cFuncsPlugin "plug-in management",
 * listener registration (::cp_register_plistener and ::cp_unregister_plistener)
 * and @ref cFuncsSymbols "dynamic symbol" functions must not be called from
 * within a plug-in listener invocation. Listener functions are registered
 * using ::cp_register_plistener.
 * 
 * @param plugin_id the plug-in identifier
 * @param old_state the old plug-in state
 * @param new_state the new plug-in state
 * @param user_data the user data pointer supplied at listener registration
 */
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);

/**
 * A logger function called to log selected plug-in framework messages. The
 * messages may be localized. Plug-in framework API functions must not
 * be called from within a logger function invocation. In a multi-threaded
 * environment logger function invocations are serialized by the framework.
 * Logger functions are registered using ::cp_register_logger.
 *
 * @param severity the severity of the message
 * @param msg the message to be logged, possibly localized
 * @param apid the identifier of the activating plug-in or NULL for the main program
 * @param user_data the user data pointer given when the logger was registered
 */
typedef void (*cp_logger_func_t)(cp_log_severity_t severity, const char *msg, const char *apid, void *user_data);

/**
 * A fatal error handler for handling unrecoverable errors. If the error
 * handler returns then the framework aborts the program. Plug-in framework
 * API functions must not be called from within a fatal error handler
 * invocation. The fatal error handler function is set using
 * ::cp_set_fatal_error_handler.
 *
 * @param msg the possibly localized error message
 */
typedef void (*cp_fatal_error_func_t)(const char *msg);

/**
 * A run function registered by a plug-in to perform work.
 * The run function  should perform a finite chunk of work and it should
 * return a non-zero value if there is more work to be done. Run functions
 * are registered using ::cp_run_function and the usage is discussed in
 * more detail in the @ref cFuncsPluginExec "serial execution" section.
 * 
 * @param plugin_data the plug-in instance data pointer
 * @return non-zero if there is more work to be done or zero if finished
 */
typedef int (*cp_run_func_t)(void *plugin_data);

/*@}*/


/* Data structures */

/**
 * @ingroup cStructs
 * Plug-in information structure captures information about a plug-in. This
 * information can be loaded from a plug-in descriptor using
 * ::cp_load_plugin_descriptor. Information about installed plug-ins can
 * be obtained using ::cp_get_plugin_info and ::cp_get_plugins_info. This
 * structure corresponds to the @a plugin element in a plug-in descriptor.
 */
struct cp_plugin_info_t {
        
        /**
         * The obligatory unique identifier of the plugin. A recommended way
         * to generate identifiers is to use domain name service (DNS) prefixes
         * (for example, org.cpluff.ExamplePlugin) to avoid naming conflicts. This
         * corresponds to the @a id attribute of the @a plugin element in a plug-in
         * descriptor.
         */
        char *identifier;
        
        /**
         * An optional plug-in name. NULL if not available. The plug-in name is
         * intended only for display purposes and the value can be localized.
         * This corresponds to the @a name attribute of the @a plugin element in
         * a plug-in descriptor.
         */
        char *name;
        
        /**
         * An optional release version string. NULL if not available. This
         * corresponds to the @a version attribute of the @a plugin element in
         * a plug-in descriptor.
         */
        char *version;
        
        /**
         * An optional provider name. NULL if not available. This is the name of
         * the author or the organization providing the plug-in. The
         * provider name is intended only for display purposes and the value can
         * be localized. This corresponds to the @a provider-name attribute of the
         * @a plugin element in a plug-in descriptor.
         */
        char *provider_name;
        
        /**
         * Path of the plugin directory or NULL if not known. This is the
         * (absolute or relative) path to the plug-in directory containing
         * plug-in data and the plug-in runtime library. The value corresponds
         * to the path specified to ::cp_load_plugin_descriptor when loading
         * the plug-in.
         */
        char *plugin_path;
        
        /**
         * Optional ABI compatibility information. NULL if not available.
         * This is the earliest version of the plug-in interface the current
         * interface is backwards compatible with when it comes to the application
         * binary interface (ABI) of the plug-in. That is, plug-in clients compiled against
         * any plug-in interface version from @a abi_bw_compatibility to
         * @ref version (inclusive) can use the current version of the plug-in
         * binary. This describes binary or runtime compatibility.
         * The value corresponds to the @a abi-compatibility
         * attribute of the @a backwards-compatibility element in a plug-in descriptor.
         */
        char *abi_bw_compatibility;
        
        /**
         * Optional API compatibility information. NULL if not available.
         * This is the earliest version of the plug-in interface the current
         * interface is backwards compatible with when it comes to the
         * application programming interface (API) of the plug-in. That is,
         * plug-in clients written for any plug-in interface version from
         * @a api_bw_compatibility to @ref version (inclusive) can be compiled
         * against the current version of the plug-in API. This describes
         * source or build time compatibility. The value corresponds to the
         * @a api-compatibility attribute of the @a backwards-compatibility
         * element in a plug-in descriptor. 
         */
        char *api_bw_compatibility;
        
        /**
         * Optional C-Pluff version requirement. NULL if not available.
         * This is the version of the C-Pluff implementation the plug-in was
         * compiled against. It is used to determine the compatibility of
         * the plug-in runtime and the linked in C-Pluff implementation. Any
         * C-Pluff version that is backwards compatible on binary level with the
         * specified version fulfills the requirement.
         */
        char *req_cpluff_version;
        
        /** Number of import entries in the @ref imports array. */
        unsigned int num_imports;
        
        /**
         * An array of @ref num_imports import entries. These correspond to
         * @a import elements in a plug-in descriptor.
         */
        cp_plugin_import_t *imports;

    /**
     * The base name of the plug-in runtime library, or NULL if none.
     * A platform specific prefix (for example, "lib") and an extension
     * (for example, ".dll" or ".so") may be added to the base name.
     * This corresponds to the @a library attribute of the
     * @a runtime element in a plug-in descriptor.
     */
    char *runtime_lib_name;
    
    /**
     * The symbol pointing to the plug-in runtime function information or
     * NULL if none. The symbol with this name should point to an instance of
     * @ref cp_plugin_runtime_t structure. This corresponds to the
     * @a funcs attribute of the @a runtime element in a plug-in descriptor. 
     */
    char *runtime_funcs_symbol;
    
        /** Number of extension points in @ref ext_points array. */
        unsigned int num_ext_points;
        
        /**
         * An array of @ref num_ext_points extension points provided by this
         * plug-in. These correspond to @a extension-point elements in a
         * plug-in descriptor.
         */
        cp_ext_point_t *ext_points;
        
        /** Number of extensions in @ref extensions array. */
        unsigned int num_extensions;
        
        /**
         * An array of @ref num_extensions extensions provided by this
         * plug-in. These correspond to @a extension elements in a plug-in
         * descriptor.
         */
        cp_extension_t *extensions;

};

/**
 * @ingroup cStructs
 * Information about plug-in import. Plug-in import structures are
 * contained in @ref cp_plugin_info_t::imports.
 */
struct cp_plugin_import_t {
        
        /**
         * The identifier of the imported plug-in. This corresponds to the
         * @a plugin attribute of the @a import element in a plug-in descriptor.
         */
        char *plugin_id;
        
        /**
         * An optional version requirement. NULL if no version requirement.
         * This is the version of the imported plug-in the importing plug-in was
         * compiled against. Any version of the imported plug-in that is
         * backwards compatible with this version fulfills the requirement.
         * This corresponds to the @a if-version attribute of the @a import
         * element in a plug-in descriptor.
         */
        char *version;
        
        /**
         * Is this import optional. 1 for optional and 0 for mandatory import.
         * An optional import causes the imported plug-in to be started if it is
         * available but does not stop the importing plug-in from starting if the
         * imported plug-in is not available. If the imported plug-in is available
         * but the API version conflicts with the API version requirement then the
         * importing plug-in fails to start. This corresponds to the @a optional
         * attribute of the @a import element in a plug-in descriptor.
         */
        int optional;
};

/**
 * @ingroup cStructs
 * Extension point structure captures information about an extension
 * point. Extension point structures are contained in
 * @ref cp_plugin_info_t::ext_points.
 */
struct cp_ext_point_t {

        /**
         * A pointer to plug-in information containing this extension point.
         * This reverse pointer is provided to make it easy to get information
         * about the plug-in which is hosting a particular extension point.
         */
        cp_plugin_info_t *plugin;
        
        /**
         * The local identifier uniquely identifying the extension point within the
         * host plug-in. This corresponds to the @name id attribute of an
         * @a extension-point element in a plug-in descriptor.
         */
        char *local_id;
        
        /**
         * The unique identifier of the extension point. This is automatically
         * constructed by concatenating the identifier of the host plug-in and
         * the local identifier of the extension point.
         */
        char *identifier;

        /**
         * An optional extension point name. NULL if not available. The extension
         * point name is intended for display purposes only and the value can be
         * localized. This corresponds to the @a name attribute of
         * an @a extension-point element in a plug-in descriptor.
         */
        char *name;
        
        /**
         * An optional path to the extension schema definition.
         * NULL if not available. The path is relative to the plug-in directory.
         * This corresponds to the @a schema attribute
         * of an @a extension-point element in a plug-in descriptor.
         */
        char *schema_path;
};

/**
 * @ingroup cStructs
 * Extension structure captures information about an extension. Extension
 * structures are contained in @ref cp_plugin_info_t::extensions.
 */
struct cp_extension_t {

        /** 
         * A pointer to plug-in information containing this extension.
         * This reverse pointer is provided to make it easy to get information
         * about the plug-in which is hosting a particular extension.
         */
        cp_plugin_info_t *plugin;
        
        /**
         * The unique identifier of the extension point this extension is
         * attached to. This corresponds to the @a point attribute of an
         * @a extension element in a plug-in descriptor.
         */
        char *ext_point_id;
        
        /**
         * An optional local identifier uniquely identifying the extension within
         * the host plug-in. NULL if not available. This corresponds to the
         * @a id attribute of an @a extension element in a plug-in descriptor.
         */
        char *local_id;

    /**
     * An optional unique identifier of the extension. NULL if not available.
     * This is automatically constructed by concatenating the identifier
     * of the host plug-in and the local identifier of the extension.
     */
    char *identifier;
         
        /** 
         * An optional extension name. NULL if not available. The extension name
         * is intended for display purposes only and the value can be localized.
         * This corresponds to the @a name attribute
         * of an @a extension element in a plug-in descriptor.
         **/
        char *name;
        
        /**
         * Extension configuration starting with the extension element.
         * This includes extension configuration information as a tree of
         * configuration elements. These correspond to the @a extension
         * element and its contents in a plug-in descriptor.
         */
        cp_cfg_element_t *configuration;
};

/**
 * @ingroup cStructs
 * A configuration element contains configuration information for an
 * extension. Utility functions ::cp_lookup_cfg_element and
 * ::cp_lookup_cfg_value can be used for traversing the tree of
 * configuration elements. Pointer to the root configuration element is
 * stored at @ref cp_extension_t::configuration and others are contained as
 * @ref cp_cfg_element_t::children "children" of parent elements.
 */
struct cp_cfg_element_t {
        
        /**
         * The name of the configuration element. This corresponds to the name of
         * the element in a plug-in descriptor.
         */
        char *name;

        /** Number of attribute name, value pairs in the @ref atts array. */
        unsigned int num_atts;
        
        /**
         * An array of pointers to alternating attribute names and values.
         * Attribute values can be localized.
         */
        char **atts;
        
        /**
          * An optional value of this configuration element. NULL if not available.
          * The value can be localized. This corresponds to the
          * text contents of the element in a plug-in descriptor.
          */
        char *value;
        
        /** A pointer to the parent element or NULL if this is a root element. */
        cp_cfg_element_t *parent;
        
        /** The index of this element among its siblings (0-based). */
        unsigned int index;
        
        /** Number of children in the @ref children array. */
        unsigned int num_children;

        /**
         * An array of @ref num_children childrens of this element. These
         * correspond to child elements in a plug-in descriptor.
         */
        cp_cfg_element_t *children;
};

/**
 * @ingroup cStructs
 * Container for plug-in runtime information. A plug-in runtime defines a
 * static instance of this structure to pass information to the plug-in
 * framework. The plug-in framework then uses the information
 * to create and control plug-in instances. The symbol pointing
 * to the runtime information instance is named by the @a funcs
 * attribute of the @a runtime element in a plug-in descriptor.
 * 
 * The following graph displays how these functions are used to control the
 * state of the plug-in instance. 
 * 
 * @dot
 * digraph lifecycle {
 *   rankdir=LR;
 *   node [shape=ellipse, fontname=Helvetica, fontsize=10];
 *   edge [fontname=Helvetica, fontsize=10];
 *   none [label="no instance"];
 *   inactive [label="inactive"];
 *   active [label="active"];
 *   none -> inactive [label="create", URL="\ref create"];
 *   inactive -> active [label="start", URL="\ref start"];
 *   active -> inactive [label="stop", URL="\ref stop"];
 *   inactive -> none [label="destroy", URL="\ref destroy"];
 * }
 * @enddot
 */
struct cp_plugin_runtime_t {

        /**
         * An initialization function called to create a new plug-in
         * runtime instance. The initialization function initializes and
         * returns an opaque plug-in instance data pointer which is then
         * passed on to other control functions. This data pointer should
         * be used to access plug-in instance specific data. For example,
         * the context reference must be stored as part of plug-in instance
         * data if the plug-in runtime needs it. On failure, this function
         * must return NULL.
         * 
         * C-Pluff API functions must not be called from within a create
         * function invocation and symbols from imported plug-ins must not be
         * used because they may not available yet.
         * 
         * @param ctx the plug-in context of the new plug-in instance
         * @return an opaque pointer to plug-in instance data or NULL on failure
         */  
        void *(*create)(cp_context_t *ctx);

        /**
         * A start function called to start a plug-in instance.
         * The start function must return zero (CP_OK) on success and non-zero
         * on failure. If the start fails then the stop function (if any) is
         * called to clean up plug-in state. @ref cFuncsInit "Library initialization",
         * @ref cFuncsContext "plug-in context management" and
         * @ref cFuncsPlugin "plug-in management" functions must not be
         * called from within a start function invocation. The start function
         * pointer can be NULL if the plug-in runtime does not have a start
         * function.
         * 
         * The start function implementation should set up plug-in and return
         * promptly. If there is further work to be done then a plug-in can
         * start a thread or register a run function using ::cp_run_function.
         * Symbols from imported plug-ins are guaranteed to be available for
         * the start function.
         * 
         * @param data an opaque pointer to plug-in instance data
         * @return non-zero on success, or zero on failure
         */
        int (*start)(void *data);
        
        /**
         * A stop function called to stop a plugin instance.
         * This function must cease all plug-in runtime activities.
         * @ref cFuncsInit "Library initialization",
         * @ref cFuncsContext "plug-in context management",
         * @ref cFuncsPlugin "plug-in management"
         * functions, ::cp_run_function and ::cp_resolve_symbol must not be called
         * from within a stop function invocation. The stop function pointer can
         * be NULL if the plug-in runtime does not have a stop function.
         * It is guaranteed that no run functions registered by the plug-in are
         * called simultaneously or after the call to the stop function.
         * 
         * The stop function should release any external resources hold by
         * the plug-in. Dynamically resolved symbols are automatically released
         * and dynamically defined symbols and registered run functions are
         * automatically unregistered after the call to stop function.
         * Resolved external symbols are still available for the stop function
         * and symbols provided by the plug-in should remain available
         * after the call to stop function (although functionality might be
         * limited). Final cleanup can be safely done in the destroy function.
         *
         * @param data an opaque pointer to plug-in instance data
         */
        void (*stop)(void *data);

        /**
         * A destroy function called to destroy a plug-in instance.
         * This function should release any plug-in instance data.
         * The plug-in is stopped before this function is called.
         * C-Pluff API functions must not be called from within a destroy
         * function invocation and symbols from imported plug-ins must not be
         * used because they may not be available anymore. Correspondingly,
         * it is guaranteed that the symbols provided by the plug-in are not
         * used by other plug-ins when destroy function has been called.
         *
         * @param data an opaque pointer to plug-in instance data
         */
        void (*destroy)(void *data);

};

/**
 * @ingroup cStructs
 * A plug-in loader instance. Plug-in loaders are responsible for
 * loading plug-in information from plug-in collections and providing it
 * to the framework. The loader exposes its services to the
 * framework via an instance of this structure which is obtained from a
 * loader-specific constructor function.
 *
 * @ref cFuncsInit "Library initialization" and
 * @ref cFuncsContext "plug-in context management"
 * functions must not be called from within the service functions stored
 * in this structure.
 *
 * The framework itself provides a plug-in loader capable of loading plugins
 * from a local plug-in collection (a directory containing plugins).
 * However, applications may provide custom plug-in loaders, for example to
 * load plug-ins from remote plug-in collections.
 */
struct cp_plugin_loader_t {

        /**
         * An opaque data pointer for this plug-in loader instance. This data
         * pointer is passed on to service functions specified by this
         * structure. The loader-specific constructor initializes it to
         * instance-specific data such as configuration of the plug-in collection.
         */
        void *data;

        /**
         * A function called to load plug-in information from the configured
         * plug-in collection. Loads and returns plug-in descriptors for
         * compatible plug-ins found in the plug-in collection. The returned
         * plug-in information must be loaded using ::cp_load_plugin_descriptor.
         * This function is called when ::cp_scan_plugins is called. The data
         * returned by this function is released by calling the
         * @a release_plugins function when the array is not needed anymore.
         * This function returns NULL on failure.
         *
         * The runtime code and data of the returned plug-ins does not need to
         * be locally available. The @a resolve_files function is explicitly
         * called when the runtime code and data is needed. The plug-in
         * path must be initialized into a location that will hold the plug-in
         * code and data after the plug-in has been resolved. In practice this
         * means that the plug-in descriptor must be loaded from a path that will
         * hold plug-in and data after the plug-in has been resolved.
         *
         * @param data plug-in loader data
         * @param ctx the associatd plug-in context
         * @return pointer to a NULL-terminated array of plug-in information pointers, or NULL on failure
         */
        cp_plugin_info_t **(*scan_plugins)(void *data, cp_context_t *ctx);
        
        /**
         * A function called to ensure that the plug-in runtime code and data
         * is locally available. Makes the runtime code and data of the specified
         * plug-in available at the plug-in path. The specified plug-in has been
         * obtained from a call to @a scan_plugins. Does nothing if the plug-in
         * runtime data is already locally available. This function may be NULL
         * if plug-ing runtime data is always available after successful scan.
         *
         * @param data plug-in loader data
         * @param ctx the associated plug-in context
         * @param plugin plug-in information for the plug-in being resolved
         * @return non-zero on success or zero on failure
         */
        int (*resolve_files)(void *data, cp_context_t *ctx, cp_plugin_info_t *plugin);

        /**
         * A function called to release plug-in information returned by the
         * @a scan_plugins function. This function must call ::cp_release_info
         * on each plug-in information structure and deallocate the pointer array.
         * If this function is NULL, the framework will release plug-in
         * information structures and deallocate the pointer array using
         * @a free.
         *
         * @param data plug-in loader data
         * @param ctx the associated plug-in context
         * @param plugins pointer to a NULL-terminated array of plug-in information pointers obtained from a call to scan_plugins
         */     
        void (*release_plugins)(void *data, cp_context_t *ctx, cp_plugin_info_t **plugins);

};

/*@}*/


/* ------------------------------------------------------------------------
 * Function declarations
 * ----------------------------------------------------------------------*/

/**
 * @defgroup cFuncs Functions
 *
 * C API functions. The C-Pluff C API functions and
 * any data exposed by them are generally thread-safe if the library has been
 * compiled with multi-threading support. The
 * @ref cFuncsInit "framework initialization functions"
 * are exceptions, they are not thread-safe.
 */

/**
 * @defgroup cFuncsFrameworkInfo Framework information
 * @ingroup cFuncs
 *
 * These functions can be used to query runtime information about the
 * linked in C-Pluff implementation. They may be used by the main program or
 * by a plug-in runtime.
 */
/*@{*/

/**
 * Returns the release version string of the linked in C-Pluff
 * implementation.
 * 
 * @return the C-Pluff release version string
 */
CP_C_API const char *cp_get_version(void) CP_GCC_PURE;

/**
 * Returns the canonical host type associated with the linked in C-Pluff implementation.
 * A multi-platform installation manager could use this information to
 * determine what plug-in versions to install.
 * 
 * @return the canonical host type
 */
CP_C_API const char *cp_get_host_type(void) CP_GCC_PURE;

/*@}*/


/**
 * @defgroup cFuncsInit Framework initialization
 * @ingroup cFuncs
 *
 * These functions are used for framework initialization.
 * They are intended to be used by the main program. These functions are
 * not thread safe.
 */
/*@{*/

/**
 * Sets the fatal error handler called on non-recoverable errors. The default
 * error handler prints the error message out to standard error and aborts
 * the program. If the user specified error handler returns then the framework
 * will abort the program. Setting NULL error handler will restore the default
 * handler. This function is not thread-safe and it should be called
 * before initializing the framework to catch all fatal errors.
 * 
 * @param error_handler the fatal error handler
 */
CP_C_API void cp_set_fatal_error_handler(cp_fatal_error_func_t error_handler);

/**
 * Initializes the plug-in framework. This function must be called
 * by the main program before calling any other plug-in framework
 * functions except @ref cFuncsFrameworkInfo "framework information" functions and
 * ::cp_set_fatal_error_handler. This function may be
 * called several times but it is not thread-safe. Library resources
 * should be released by calling ::cp_destroy when the framework is
 * not needed anymore.
 *
 * Additionally, to enable localization support, the main program should
 * set the current locale using @code setlocale(LC_ALL, "") @endcode
 * before calling this function.
 *
 * @return @ref CP_OK (zero) on success or error code on failure
 */
CP_C_API cp_status_t cp_init(void);

/**
 * Destroys the plug-in framework and releases the resources used by it.
 * The plug-in framework is only destroyed after this function has
 * been called as many times as ::cp_init. This function is not
 * thread-safe. Plug-in framework functions other than ::cp_init,
 * ::cp_get_framework_info and ::cp_set_fatal_error_handler
 * must not be called after the plug-in framework has been destroyed.
 * All contexts are destroyed and all data references returned by the
 * framework become invalid.
 */
CP_C_API void cp_destroy(void);

/*@}*/


/**
 * @defgroup cFuncsContext Plug-in context initialization
 * @ingroup cFuncs
 *
 * These functions are used to manage plug-in contexts from the main
 * program perspective. They are not intended to be used by a plug-in runtime.
 * From the main program perspective a plug-in context is a container for
 * installed plug-ins. There can be several plug-in context instances if there
 * are several independent sets of plug-ins. However, different plug-in
 * contexts are not very isolated from each other in practice because the
 * global symbols exported by a plug-in runtime in one context are visible to
 * all plug-ins in all context instances.
 */
/*@{*/

/**
 * Creates a new plug-in context which can be used as a container for plug-ins.
 * Plug-ins are loaded and installed into a specific context. The main
 * program may have more than one plug-in context but the plug-ins that
 * interact with each other should be placed in the same context. The
 * resources associated with the context are released by calling
 * ::cp_destroy_context when the context is not needed anymore. Remaining
 * contexts are automatically destroyed when the plug-in framework is
 * destroyed. 
 * 
 * @param status pointer to the location where status code is to be stored, or NULL
 * @return the newly created plugin context, or NULL on failure
 */
CP_C_API cp_context_t * cp_create_context(cp_status_t *status);

/**
 * Changes the file name in the plug-in the plug-in descriptor is loaded from.
 * The default name is "plugin.xml"
 *
 * @param ctx the context to change the plug-in descriptor file name in
 * @param name the new plug-in descriptor file name
 */
CP_C_API void cp_set_plugin_descriptor_name(cp_context_t *ctx, const char *name);

/**
 * Changes the XML root element's name in plug-in descriptor.
 * This also changes the attribute name to be used in the "import" element.
 * The default name is "plugin".
 *
 * @param ctx the context to change the plug-in descriptor's XML root element's name in
 * @param root the new XML root element name
 */
CP_C_API void cp_set_plugin_descriptor_root_element(cp_context_t *ctx, const char *root);

/**
 * Destroys the specified plug-in context and releases the associated resources.
 * Stops and uninstalls all plug-ins in the context. The context must not be
 * accessed after calling this function.
 * 
 * @param ctx the context to be destroyed
 */
CP_C_API void cp_destroy_context(cp_context_t *ctx) CP_GCC_NONNULL(1);

/**
 * Registers a local plug-in collection with a plug-in context. A local plug-in collection
 * is a directory that has plug-ins as its immediate subdirectories. The
 * plug-in context will scan the directory when ::cp_scan_plugins is called.
 * Returns @ref CP_OK if the directory has already been registered. A plug-in
 * collection can be unregistered using ::cp_unregister_pcollection or
 * ::cp_unregister_pcollections.
 *
 * This is equivalent to having registered a local plug-in loader and
 * registering a plug-in directory with it.
 *
 * @param ctx the plug-in context
 * @param dir the directory
 * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if insufficient memory
 */
CP_C_API cp_status_t cp_register_pcollection(cp_context_t *ctx, const char *dir) CP_GCC_NONNULL(1, 2);

/**
 * Unregisters a previously registered plug-in collection from a
 * plug-in context. Plug-ins already loaded from the collection are not
 * affected. Does nothing if the directory has not been registered.
 * Plug-in collections can be registered using ::cp_register_pcollection.
 * 
 * This is equivalent to having registered a local plug-in loader and
 * unregistering a plug-in directory with it.
 *
 * @param ctx the plug-in context
 * @param dir the previously registered directory
 */
CP_C_API void cp_unregister_pcollection(cp_context_t *ctx, const char *dir) CP_GCC_NONNULL(1, 2);

/**
 * Unregisters all plug-in collections from a plug-in context.
 * Plug-ins already loaded are not affected. Plug-in collections can
 * be registered using ::cp_register_pcollection.
 * 
 * This is equivalent to having registered a local plug-in loader and
 * unregistering all plug-in directories with it.
 *
 * @param ctx the plug-in context
 */
CP_C_API void cp_unregister_pcollections(cp_context_t *ctx) CP_GCC_NONNULL(1);

/**
 * Registers a plug-in loader that will be used to load plug-ins into this
 * context when ::cp_scan_plugins is called. Several plug-in loaders can be
 * registered for a context. Returns @ref CP_OK if the same loader instance
 * has already been registered with the context. A loader can be unregistered
 * using ::cp_unregister_ploader or ::cp_unregister_ploaders. An alternative
 * to explicitly registering a plug-in loader is to register a local plug-in
 * collection
 *
 * @param ctx the plug-in context
 * @param loader the plug-in loader
 * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if insufficient memory
 */
CP_C_API cp_status_t cp_register_ploader(cp_context_t *ctx, cp_plugin_loader_t *loader) CP_GCC_NONNULL(1, 2);

/**
 * Unregisters a previously registered plug-in loader from a plug-in context.
 * All plug-ins loaded by the loader are uninstalled. Does nothing if the
 * specified loader has not been registered. Plug-in loaders can be registered
 * using ::cp_register_ploader.
 *
 * @param ctx the plug-in context
 * @param loader the plug-in loader
 */
CP_C_API void cp_unregister_ploader(cp_context_t *ctx, cp_plugin_loader_t *loader) CP_GCC_NONNULL(1, 2);

/**
 * Unregisters all registered plug-in loaders from a plug-in context.
 * All plug-ins loaded by the unregistered loaders are uninstalled. Plug-in
 * loaders can be registered using ::cp_register_ploader.
 *
 * @param ctx the plug-in context
 */
CP_C_API void cp_unregister_ploaders(cp_context_t *ctx) CP_GCC_NONNULL(1);

/*@}*/


/**
 * @defgroup cFuncsLogging Logging
 * @ingroup cFuncs
 *
 * These functions can be used to receive and emit log messages related
 * to a particular plug-in context. They can be used by the main program
 * or by a plug-in runtime.
 */
/*@{*/

/**
 * Registers a logger with a plug-in context or updates the settings of a
 * registered logger. The logger will receive selected log messages.
 * If the specified logger is not yet known, a new logger registration
 * is made, otherwise the settings for the existing logger are updated.
 * The logger can be unregistered using ::cp_unregister_logger and it is
 * automatically unregistered when the registering plug-in is stopped or
 * when the context is destroyed. 
 *
 * @param ctx the plug-in context to log
 * @param logger the logger function to be called
 * @param user_data the user data pointer passed to the logger
 * @param min_severity the minimum severity of messages passed to logger
 * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if insufficient memory
 */
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);

/**
 * Removes a logger registration.
 *
 * @param ctx the plug-in context
 * @param logger the logger function to be unregistered
 */
CP_C_API void cp_unregister_logger(cp_context_t *ctx, cp_logger_func_t logger) CP_GCC_NONNULL(1, 2);

/**
 * Emits a new log message.
 * 
 * @param ctx the plug-in context
 * @param severity the severity of the event
 * @param msg the log message (possibly localized)
 */
CP_C_API void cp_log(cp_context_t *ctx, cp_log_severity_t severity, const char *msg) CP_GCC_NONNULL(1, 3);

/**
 * Returns whether a message of the specified severity would get logged.
 * 
 * @param ctx the plug-in context
 * @param severity the target logging severity
 * @return whether a message of the specified severity would get logged
 */
CP_C_API int cp_is_logged(cp_context_t *ctx, cp_log_severity_t severity) CP_GCC_NONNULL(1);

/*@}*/


/**
 * @defgroup cFuncsPlugin Plug-in management
 * @ingroup cFuncs
 *
 * These functions can be used to manage plug-ins. They are intended to be
 * used by the main program.
 */
/*@{*/

/**
 * Loads a plug-in descriptor from the specified plug-in installation
 * path and returns information about the plug-in. The plug-in descriptor
 * is validated during loading. Possible loading errors are reported via the
 * specified plug-in context. The plug-in is not installed to the context.
 * If operation fails or the descriptor
 * is invalid then NULL is returned. The caller must release the returned
 * information by calling ::cp_release_info when it does not
 * need the information anymore, typically after installing the plug-in.
 * The returned plug-in information must not be modified.
 * 
 * @param ctx the plug-in context
 * @param path the installation path of the plug-in
 * @param status a pointer to the location where status code is to be stored, or NULL
 * @return pointer to the information structure or NULL if error occurs
 */
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);

/**
 * Loads a plug-in descriptor from the specified block of memory and returns
 * information about the plug-in. The plug-in descriptor
 * is validated during loading. Possible loading errors are reported via the
 * specified plug-in context. The plug-in is not installed to the context.
 * If operation fails or the descriptor
 * is invalid then NULL is returned. The caller must release the returned
 * information by calling ::cp_release_info when it does not
 * need the information anymore, typically after installing the plug-in.
 * The returned plug-in information must not be modified.
 * 
 * @param ctx the plug-in context
 * @param buffer the buffer containing the plug-in descriptor.
 * @param buffer_len the length of the buffer.
 * @param status a pointer to the location where status code is to be stored, or NULL
 * @return pointer to the information structure or NULL if error occurs
 */
CP_C_API cp_plugin_info_t * cp_load_plugin_descriptor_from_memory(cp_context_t *ctx, const char *buffer, unsigned int buffer_len, cp_status_t *status) CP_GCC_NONNULL(1, 2);

/**
 * Installs the plug-in described by the specified plug-in information
 * structure to the specified plug-in context. The plug-in information
 * must have been loaded using ::cp_load_plugin_descriptor with the same
 * plug-in context.
 * The installation fails on #CP_ERR_CONFLICT if the context already
 * has an installed plug-in with the same plug-in identifier. Installation
 * also fails if the plug-in tries to install an extension point which
 * conflicts with an already installed extension point.
 * The plug-in information must not be modified but it is safe to call
 * ::cp_release_info after the plug-in has been installed.
 *
 * @param ctx the plug-in context
 * @param pi plug-in information structure
 * @return @ref CP_OK (zero) on success or an error code on failure
 */
CP_C_API cp_status_t cp_install_plugin(cp_context_t *ctx, cp_plugin_info_t *pi) CP_GCC_NONNULL(1, 2);

/**
 * Scans for plug-ins in the registered plug-in directories, installing
 * new plug-ins and upgrading installed plug-ins. This function can be used to
 * initially load the plug-ins and to later rescan for new plug-ins.
 * 
 * When several versions of the same plug-in is available the most recent
 * version will be installed. The upgrade behavior depends on the specified
 * @ref cScanFlags "flags". If #CP_SP_UPGRADE is set then upgrades to installed plug-ins are
 * allowed. The old version is unloaded and the new version installed instead.
 * If #CP_SP_STOP_ALL_ON_UPGRADE is set then all active plug-ins are stopped
 * if any plug-ins are to be upgraded. If #CP_SP_STOP_ALL_ON_INSTALL is set then
 * all active plug-ins are stopped if any plug-ins are to be installed or
 * upgraded. Finally, if #CP_SP_RESTART_ACTIVE is set all currently active
 * plug-ins will be restarted after the changes (if they were stopped).
 * 
 * When removing plug-in files from the plug-in directories, the
 * plug-ins to be removed must be first unloaded. Therefore this function
 * does not check for removed plug-ins.
 * 
 * @param ctx the plug-in context
 * @param flags the bitmask of flags
 * @return @ref CP_OK (zero) on success or an error code on failure
 */
CP_C_API cp_status_t cp_scan_plugins(cp_context_t *ctx, int flags) CP_GCC_NONNULL(1);

/**
 * Starts a plug-in. Also starts any imported plug-ins. If the plug-in is
 * already starting then
 * this function blocks until the plug-in has started or failed to start.
 * If the plug-in is already active then this function returns immediately.
 * If the plug-in is stopping then this function blocks until the plug-in
 * has stopped and then starts the plug-in.
 * 
 * @param ctx the plug-in context
 * @param id identifier of the plug-in to be started
 * @return @ref CP_OK (zero) on success or an error code on failure
 */
CP_C_API cp_status_t cp_start_plugin(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1, 2);

/**
 * Stops a plug-in. First stops any dependent plug-ins that are currently
 * active. Then stops the specified plug-in. If the plug-in is already
 * stopping then this function blocks until the plug-in has stopped. If the
 * plug-in is already stopped then this function returns immediately. If the
 * plug-in is starting then this function blocks until the plug-in has
 * started (or failed to start) and then stops the plug-in.
 * 
 * @param ctx the plug-in context
 * @param id identifier of the plug-in to be stopped
 * @return @ref CP_OK (zero) on success or @ref CP_ERR_UNKNOWN if unknown plug-in
 */
CP_C_API cp_status_t cp_stop_plugin(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1, 2);

/**
 * Stops all active plug-ins.
 * 
 * @param ctx the plug-in context
 */
CP_C_API void cp_stop_plugins(cp_context_t *ctx) CP_GCC_NONNULL(1);

/**
 * Uninstalls the specified plug-in. The plug-in is first stopped if it is active.
 * Then uninstalls the plug-in and any dependent plug-ins.
 * 
 * @param ctx the plug-in context
 * @param id identifier of the plug-in to be unloaded
 * @return @ref CP_OK (zero) on success or @ref CP_ERR_UNKNOWN if unknown plug-in
 */
CP_C_API cp_status_t cp_uninstall_plugin(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1, 2);

/**
 * Uninstalls all plug-ins. All plug-ins are first stopped and then
 * uninstalled.
 * 
 * @param ctx the plug-in context
 */
CP_C_API void cp_uninstall_plugins(cp_context_t *ctx) CP_GCC_NONNULL(1);

/*@}*/


/**
 * @defgroup cFuncsPluginInfo Plug-in and extension information
 * @ingroup cFuncs
 *
 * These functions can be used to query information about the installed
 * plug-ins, extension points and extensions or to listen for plug-in state
 * changes. They may be used by the main program or by a plug-in runtime.
 */
/*@{*/

/**
 * Returns static information about the specified plug-in. The returned
 * information must not be modified and the caller must
 * release the information by calling ::cp_release_info when the
 * information is not needed anymore. When a plug-in runtime calls this
 * function it may pass NULL as the identifier to get information about the
 * plug-in itself.
 * 
 * @param ctx the plug-in context
 * @param id identifier of the plug-in to be examined or NULL for self
 * @param status a pointer to the location where status code is to be stored, or NULL
 * @return pointer to the information structure or NULL on failure
 */
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);

/**
 * Returns static information about the installed plug-ins. The returned
 * information must not be modified and the caller must
 * release the information by calling ::cp_release_info when the
 * information is not needed anymore.
 * 
 * @param ctx the plug-in context
 * @param status a pointer to the location where status code is to be stored, or NULL
 * @param num a pointer to the location where the number of returned plug-ins is stored, or NULL
 * @return pointer to a NULL-terminated list of pointers to plug-in information
 *                      or NULL on failure
 */
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);

/**
 * Returns static information about the currently installed extension points.
 * The returned information must not be modified and the caller must
 * release the information by calling ::cp_release_info when the
 * information is not needed anymore.
 *
 * @param ctx the plug-in context
 * @param status a pointer to the location where status code is to be stored, or NULL
 * @param num filled with the number of returned extension points, if non-NULL
 * @return pointer to a NULL-terminated list of pointers to extension point
 *                      information or NULL on failure
 */
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);

/**
 * Returns static information about the currently installed extension points.
 * The returned information must not be modified and the caller must
 * release the information by calling ::cp_release_info when the
 * information is not needed anymore.
 *
 * @param ctx the plug-in context
 * @param extpt_id the extension point identifier or NULL for all extensions
 * @param status a pointer to the location where status code is to be stored, or NULL
 * @param num a pointer to the location where the number of returned extension points is to be stored, or NULL
 * @return pointer to a NULL-terminated list of pointers to extension
 *                      information or NULL on failure
 */
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);

/**
 * Releases a previously obtained reference counted information object. The
 * documentation for functions returning such information refers
 * to this function. The information must not be accessed after it has
 * been released. The framework uses reference counting to deallocate
 * the information when it is not in use anymore.
 * 
 * @param ctx the plug-in context
 * @param info the information to be released
 */
CP_C_API void cp_release_info(cp_context_t *ctx, void *info) CP_GCC_NONNULL(1, 2);

/**
 * Returns the current state of the specified plug-in. Returns
 * #CP_PLUGIN_UNINSTALLED if the specified plug-in identifier is unknown.
 * 
 * @param ctx the plug-in context
 * @param id the plug-in identifier
 * @return the current state of the plug-in
 */
CP_C_API cp_plugin_state_t cp_get_plugin_state(cp_context_t *ctx, const char *id) CP_GCC_NONNULL(1, 2);

/**
 * Registers a plug-in listener with a plug-in context. The listener is called
 * synchronously immediately after a plug-in state change. There can be several
 * listeners registered with the same context. A plug-in listener can be
 * unregistered using ::cp_unregister_plistener and it is automatically
 * unregistered when the registering plug-in is stopped or when the context
 * is destroyed.
 * 
 * @param ctx the plug-in context
 * @param listener the plug-in listener to be added
 * @param user_data user data pointer supplied to the listener
 * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if out of resources
 */
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);

/**
 * Removes a plug-in listener from a plug-in context. Does nothing if the
 * specified listener was not registered.
 * 
 * @param ctx the plug-in context
 * @param listener the plug-in listener to be removed
 */
CP_C_API void cp_unregister_plistener(cp_context_t *ctx, cp_plugin_listener_func_t listener) CP_GCC_NONNULL(1, 2);

/**
 * Traverses a configuration element tree and returns the specified element.
 * The target element is specified by a base element and a relative path from
 * the base element to the target element. The path includes element names
 * separated by slash '/'. Two dots ".." can be used to designate a parent
 * element. Returns NULL if the specified element does not exist. If there are
 * several subelements with the same name, this function chooses the first one
 * when traversing the tree.
 *
 * @param base the base configuration element
 * @param path the path to the target element
 * @return the target element or NULL if nonexisting
 */
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);

/**
 * Traverses a configuration element tree and returns the value of the
 * specified element or attribute. The target element or attribute is specified
 * by a base element and a relative path from the base element to the target
 * element or attributes. The path includes element names
 * separated by slash '/'. Two dots ".." can be used to designate a parent
 * element. The path may end with '@' followed by an attribute name
 * to select an attribute. Returns NULL if the specified element or attribute
 * does not exist or does not have a value. If there are several subelements
 * with the same name, this function chooses the first one when traversing the
 * tree.
 *
 * @param base the base configuration element
 * @param path the path to the target element
 * @return the value of the target element or attribute or NULL
 */
CP_C_API char * cp_lookup_cfg_value(cp_cfg_element_t *base, const char *path) CP_GCC_PURE CP_GCC_NONNULL(1, 2);

/*@}*/


/**
 * @defgroup cFuncsPluginExec Plug-in execution
 * @ingroup cFuncs
 *
 * These functions support a plug-in controlled execution model. Started plug-ins can
 * use ::cp_run_function to register @ref cp_run_func_t "a run function" which is called when the
 * main program calls ::cp_run_plugins or ::cp_run_plugins_step. A run
 * function should do a finite chunk of work and then return telling whether
 * there is more work to be done. A run function is automatically unregistered
 * when the plug-in is stopped. Run functions make it possible for plug-ins
 * to control the flow of execution or they can be used as a coarse
 * way of task switching if there is no multi-threading support.
 *
 * The C-Pluff distribution includes a generic main program, cpluff-loader,
 * which only acts as a plug-in loader. It loads and starts up the
 * specified plug-ins, passing any additional startup arguments to them and
 * then just calls run functions of the plug-ins. This
 * makes it is possible to put all the application specific logic in
 * plug-ins. Application does not necessarily need a main program of its own.
 * 
 * It is also safe, from framework perspective, to call these functions from
 * multiple threads. Run functions may then be executed in parallel threads.
 */
/*@{*/

/**
 * Registers a new run function. The plug-in instance data pointer is given to
 * the run function as a parameter. The run function must return zero if it has
 * finished its work or non-zero if it should be called again later. The run
 * function is unregistered when it returns zero. Plug-in framework functions
 * stopping the registering plug-in must not be called from within a run
 * function. This function does nothing if the specified run
 * function is already registered for the calling plug-in instance.
 * 
 * @param ctx the plug-in context of the registering plug-in
 * @param runfunc the run function to be registered
 * @return @ref CP_OK (zero) on success or an error code on failure
 */
CP_C_API cp_status_t cp_run_function(cp_context_t *ctx, cp_run_func_t runfunc) CP_GCC_NONNULL(1, 2);

/**
 * Runs the started plug-ins as long as there is something to run.
 * This function calls repeatedly run functions registered by started plug-ins
 * until there are no more active run functions. This function is normally
 * called by a thin main proram, a loader, which loads plug-ins, starts some
 * plug-ins and then passes control over to the started plug-ins.
 * 
 * @param ctx the plug-in context containing the plug-ins
 */
CP_C_API void cp_run_plugins(cp_context_t *ctx) CP_GCC_NONNULL(1);

/**
 * Runs one registered run function. This function calls one
 * active run function registered by a started plug-in. When the run function
 * returns this function also returns and passes control back to the main
 * program. The return value can be used to determine whether there are any
 * active run functions left. This function does nothing if there are no active
 * registered run functions.
 * 
 * @param ctx the plug-in context containing the plug-ins
 * @return whether there are active run functions waiting to be run
 */
CP_C_API int cp_run_plugins_step(cp_context_t *ctx) CP_GCC_NONNULL(1);

/**
 * Sets startup arguments for the specified plug-in context. Like for usual
 * C main functions, the first argument is expected to be the name of the
 * program being executed or an empty string and the argument array should be
 * terminated by NULL entry. If the main program is
 * about to pass startup arguments to plug-ins it should call this function
 * before starting any plug-ins in the context. The arguments are not copied
 * and the caller is responsible for keeping the argument data available once
 * the arguments have been set until the context is destroyed. Plug-ins can
 * access the startup arguments using ::cp_get_context_args.
 * 
 * @param ctx the plug-in context
 * @param argv a NULL-terminated array of arguments
 */
CP_C_API void cp_set_context_args(cp_context_t *ctx, char **argv) CP_GCC_NONNULL(1, 2);

/**
 * Returns the startup arguments associated with the specified
 * plug-in context. This function is intended to be used by a plug-in runtime.
 * Startup arguments are set by the main program using ::cp_set_context_args.
 * The returned argument count is zero and the array pointer is NULL if no
 * arguments have been set.
 * 
 * @param ctx the plug-in context
 * @param argc a pointer to a location where the number of startup arguments is stored, or NULL for none
 * @return an argument array terminated by NULL or NULL if not set
 */
CP_C_API char **cp_get_context_args(cp_context_t *ctx, int *argc) CP_GCC_NONNULL(1);

/*@}*/


/**
 * @defgroup cFuncsSymbols Dynamic symbols
 * @ingroup cFuncs
 *
 * These functions can be used to dynamically access symbols exported by the
 * plug-ins. They are intended to be used by a plug-in runtime or by the main
 * program. 
 */
/*@{*/

/**
 * Defines a context specific symbol. If a plug-in has symbols which have
 * a plug-in instance specific value then the plug-in should define those
 * symbols when it is started. The defined symbols are cleared
 * automatically when the plug-in instance is stopped. Symbols can not be
 * redefined.
 * 
 * @param ctx the plug-in context
 * @param name the name of the symbol
 * @param ptr pointer value for the symbol
 * @return @ref CP_OK (zero) on success or a status code on failure
 */
CP_C_API cp_status_t cp_define_symbol(cp_context_t *ctx, const char *name, void *ptr) CP_GCC_NONNULL(1, 2, 3);

/**
 * Resolves a symbol provided by the specified plug-in. The plug-in is started
 * automatically if it is not already active. The symbol may be context
 * specific or global. The framework first looks for a context specific
 * symbol and then falls back to resolving a global symbol exported by the
 * plug-in runtime library. The symbol can be released using
 * ::cp_release_symbol when it is not needed anymore. Pointers obtained from
 * this function must not be passed on to other plug-ins or the main
 * program.
 * 
 * When a plug-in runtime calls this function the plug-in framework creates
 * a dynamic dependency from the symbol using plug-in to the symbol
 * defining plug-in. The symbol using plug-in is stopped automatically if the
 * symbol defining plug-in is about to be stopped. If the symbol using plug-in
 * does not explicitly release the symbol then it is automatically released
 * after a call to the stop function. It is not safe to refer to a dynamically
 * resolved symbol in the stop function except to release it using
 * ::cp_release_symbol.
 * 
 * When the main program calls this function it is the responsibility of the
 * main program to always release the symbol before the symbol defining plug-in
 * is stopped. It is a fatal error if the symbol is not released before the
 * symbol defining plug-in is stopped.
 *
 * @param ctx the plug-in context
 * @param id the identifier of the symbol defining plug-in
 * @param name the name of the symbol
 * @param status a pointer to the location where the status code is to be stored, or NULL
 * @return the pointer associated with the symbol or NULL on failure
 */
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);

/**
 * Releases a previously obtained symbol. The pointer must not be used after
 * the symbol has been released. The symbol is released
 * only after as many calls to this function as there have been for
 * ::cp_resolve_symbol for the same plug-in and symbol.
 *
 * @param ctx the plug-in context
 * @param ptr the pointer associated with the symbol
 */
CP_C_API void cp_release_symbol(cp_context_t *ctx, const void *ptr) CP_GCC_NONNULL(1, 2);

/*@}*/


/**
 * @defgroup cFuncsLoaders Plug-in loaders
 * @ingroup cFuncs
 *
 * These functions are used to construct standard plug-in loaders. Currently
 * there is a single plug-in loader for loading plug-ins from local plug-in
 * collections. 
 */
/*@{*/

/**
 * Creates and returns a new instance of a local plug-in loader. The resources
 * used by the returned instance can be released by calling
 * ::cp_destroy_local_ploader when the loader is not needed anymore.
 * Remaining local plug-in loaders are automatically destroyed when the
 * plug-in framework is destroyed. The created plug-in loader can be
 * registered with a plug-in context using ::cp_register_ploader.
 *
 * @param status pointer to the location where status code is to be stored, or NULL
 * @return the new plug-in loader instance, or NULL on failure
 */
CP_C_API cp_plugin_loader_t *cp_create_local_ploader(cp_status_t *status);

/**
 * Releases the resources allocated by a previously created local plug-in
 * loader. The specified loader must have been obtained by a call to
 * ::cp_create_local_ploader. The loader to be destroyed must not be
 * registered with any plug-in context.
 *
 * @param the plug-in loader to be destroyed
 */
CP_C_API void cp_destroy_local_ploader(cp_plugin_loader_t *loader) CP_GCC_NONNULL(1);

/**
 * Registers a new directory to be scanned by the specified local
 * plug-in loader. Returns @ref CP_OK if the directory has already been
 * registered.
 *
 * @param loader the plug-in loader obtained from ::cp_create_local_ploader
 * @param dir the directory to register
 * @return @ref CP_OK (zero) on success or @ref CP_ERR_RESOURCE if insufficient memory
 */
CP_C_API cp_status_t cp_lpl_register_dir(cp_plugin_loader_t *loader, const char *dir) CP_GCC_NONNULL(1, 2);

/**
 * Unregisters a directory from the specified local plug-in loader. Does
 * nothing if the specified directory has not been registered. This does not
 * affect the status of already loaded plug-ins.
 *
 * @param loader the plug-in loader obtained from ::cp_create_local_ploader
 * @param dir the directory to unregister
 */
CP_C_API void cp_lpl_unregister_dir(cp_plugin_loader_t *loader, const char *dir) CP_GCC_NONNULL(1, 2);

/**
 * Unregisters all registered directories from the specified local plug-in
 * loader. This does not affect the status of already loaded plug-ins.
 *
 * @param loader the plug-in 
 */
CP_C_API void cp_lpl_unregister_dirs(cp_plugin_loader_t *loader) CP_GCC_NONNULL(1);

/*@}*/


#ifdef __cplusplus
}
#endif /*__cplusplus*/

#endif /*CPLUFF_H_*/