path: root/lib/cpluff/libcpluff/cpluff.h

/*-------------------------------------------------------------------------
 * 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.
 */

#ifdef _WIN32
#include "win32/cpluffdef.h"
#else
#include "cpluffdef.h"
#endif

#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_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, the 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);

};

/*@}*/


/* ------------------------------------------------------------------------
 * 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);

/**
 * 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 plug-in collection with a plug-in context. A 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.
 * 
 * @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.
 * 
 * @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.
 * 
 * @param ctx the plug-in context
 */
CP_C_API void cp_unregister_pcollections(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_plugin_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_plugin_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);

/*@}*/


#ifdef __cplusplus
}
#endif /*__cplusplus*/

#endif /*CPLUFF_H_*/