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_*/
cp_uninstall_plugins
CP_IMPORT void cp_uninstall_plugins(cp_context_t *ctx)
Uninstalls all plug-ins.
cp_extension_t::plugin
cp_plugin_info_t * plugin
A pointer to plug-in information containing this extension.
Definition: cpluff.h:621
cp_set_context_args
CP_IMPORT void cp_set_context_args(cp_context_t *ctx, char **argv)
Sets startup arguments for the specified plug-in context.
cp_unregister_pcollections
CP_IMPORT void cp_unregister_pcollections(cp_context_t *ctx)
Unregisters all plug-in collections from a plug-in context.
cp_plugin_info_t::name
char * name
An optional plug-in name.
Definition: cpluff.h:416
cp_ext_point_t
Definition: cpluff.h:569
CP_OK
@ CP_OK
Operation was performed successfully (equals to zero).
Definition: cpluff.h:139
cp_plugin_loader_t::resolve_files
int(* resolve_files)(void *data, cp_context_t *ctx, cp_plugin_info_t *plugin)
A function called to ensure that the plug-in runtime code and data is locally available.
Definition: cpluff.h:886
CP_ERR_DEPENDENCY
@ CP_ERR_DEPENDENCY
Plug-in dependencies could not be satisfied.
Definition: cpluff.h:157
cp_plugin_info_t::identifier
char * identifier
The obligatory unique identifier of the plugin.
Definition: cpluff.h:408
cp_register_ploader
CP_IMPORT cp_status_t cp_register_ploader(cp_context_t *ctx, cp_plugin_loader_t *loader)
Registers a plug-in loader that will be used to load plug-ins into this context when cp_scan_plugins ...
CP_PLUGIN_UNINSTALLED
@ CP_PLUGIN_UNINSTALLED
Plug-in is not installed.
Definition: cpluff.h:181
cp_plugin_info_t::plugin_path
char * plugin_path
Path of the plugin directory or NULL if not known.
Definition: cpluff.h:441
cp_plugin_info_t::num_extensions
unsigned int num_extensions
Number of extensions in extensions array.
Definition: cpluff.h:517
cp_load_plugin_descriptor
CP_IMPORT cp_plugin_info_t * cp_load_plugin_descriptor(cp_context_t *ctx, const char *path, cp_status_t *status)
Loads a plug-in descriptor from the specified plug-in installation path and returns information about...
cp_register_pcollection
CP_IMPORT cp_status_t cp_register_pcollection(cp_context_t *ctx, const char *dir)
Registers a local plug-in collection with a plug-in context.
cp_plugin_info_t::num_ext_points
unsigned int num_ext_points
Number of extension points in ext_points array.
Definition: cpluff.h:507
cp_lpl_unregister_dir
CP_IMPORT void cp_lpl_unregister_dir(cp_plugin_loader_t *loader, const char *dir)
Unregisters a directory from the specified local plug-in loader.
cp_set_plugin_descriptor_name
CP_IMPORT void cp_set_plugin_descriptor_name(cp_context_t *ctx, const char *name)
Changes the file name in the plug-in the plug-in descriptor is loaded from.
cp_release_symbol
CP_IMPORT void cp_release_symbol(cp_context_t *ctx, const void *ptr)
Releases a previously obtained symbol.
cp_ext_point_t::plugin
cp_plugin_info_t * plugin
A pointer to plug-in information containing this extension point.
Definition: cpluff.h:576
cp_plugin_info_t::imports
cp_plugin_import_t * imports
An array of num_imports import entries.
Definition: cpluff.h:487
cp_cfg_element_t::num_atts
unsigned int num_atts
Number of attribute name, value pairs in the atts array.
Definition: cpluff.h:679
cp_plugin_import_t::plugin_id
char * plugin_id
The identifier of the imported plug-in.
Definition: cpluff.h:539
cp_register_logger
CP_IMPORT cp_status_t cp_register_logger(cp_context_t *ctx, cp_logger_func_t logger, void *user_data, cp_log_severity_t min_severity)
Registers a logger with a plug-in context or updates the settings of a registered logger.
cp_status_t
cp_status_t
Definition: cpluff.h:133
CP_PLUGIN_ACTIVE
@ CP_PLUGIN_ACTIVE
Plug-in has been successfully started and it has not yet been stopped.
Definition: cpluff.h:230
cp_get_context_args
CP_IMPORT char ** cp_get_context_args(cp_context_t *ctx, int *argc)
Returns the startup arguments associated with the specified plug-in context.
CP_ERR_UNKNOWN
@ CP_ERR_UNKNOWN
The specified object is unknown to the framework.
Definition: cpluff.h:145
cp_cfg_element_t::atts
char ** atts
An array of pointers to alternating attribute names and values.
Definition: cpluff.h:685
cp_get_plugins_info
CP_IMPORT cp_plugin_info_t ** cp_get_plugins_info(cp_context_t *ctx, cp_status_t *status, int *num)
Returns static information about the installed plug-ins.
cp_cfg_element_t::name
char * name
The name of the configuration element.
Definition: cpluff.h:676
cp_plugin_loader_t
Definition: cpluff.h:839
CP_ERR_IO
@ CP_ERR_IO
An I/O error occurred.
Definition: cpluff.h:148
cp_init
CP_IMPORT cp_status_t cp_init(void)
Initializes the plug-in framework.
cp_cfg_element_t::children
cp_cfg_element_t * children
An array of num_children childrens of this element.
Definition: cpluff.h:707
cp_ext_point_t::schema_path
char * schema_path
An optional path to the extension schema definition.
Definition: cpluff.h:606
cp_lpl_register_dir
CP_IMPORT cp_status_t cp_lpl_register_dir(cp_plugin_loader_t *loader, const char *dir)
Registers a new directory to be scanned by the specified local plug-in loader.
cp_stop_plugins
CP_IMPORT void cp_stop_plugins(cp_context_t *ctx)
Stops all active plug-ins.
cp_get_plugin_info
CP_IMPORT cp_plugin_info_t * cp_get_plugin_info(cp_context_t *ctx, const char *id, cp_status_t *status)
Returns static information about the specified plug-in.
cp_plugin_runtime_t::start
int(* start)(void *data)
A start function called to start a plug-in instance.
Definition: cpluff.h:778
cp_destroy_context
CP_IMPORT void cp_destroy_context(cp_context_t *ctx)
Destroys the specified plug-in context and releases the associated resources.
cp_ext_point_t::name
char * name
An optional extension point name.
Definition: cpluff.h:598
cp_plugin_info_t::req_cpluff_version
char * req_cpluff_version
Optional C-Pluff version requirement.
Definition: cpluff.h:478
cp_run_func_t
int(* cp_run_func_t)(void *plugin_data)
A run function registered by a plug-in to perform work.
Definition: cpluff.h:384
CP_LOG_INFO
@ CP_LOG_INFO
Used for informational messages such as plug-in state changes.
Definition: cpluff.h:247
cp_get_ext_points_info
CP_IMPORT cp_ext_point_t ** cp_get_ext_points_info(cp_context_t *ctx, cp_status_t *status, int *num)
Returns static information about the currently installed extension points.
cp_plugin_runtime_t::stop
void(* stop)(void *data)
A stop function called to stop a plugin instance.
Definition: cpluff.h:803
cp_logger_func_t
void(* cp_logger_func_t)(cp_log_severity_t severity, const char *msg, const char *apid, void *user_data)
A logger function called to log selected plug-in framework messages.
Definition: cpluff.h:361
cp_run_function
CP_IMPORT cp_status_t cp_run_function(cp_context_t *ctx, cp_run_func_t runfunc)
Registers a new run function.
cp_run_plugins_step
CP_IMPORT int cp_run_plugins_step(cp_context_t *ctx)
Runs one registered run function.
cp_create_context
CP_IMPORT cp_context_t * cp_create_context(cp_status_t *status)
Creates a new plug-in context which can be used as a container for plug-ins.
cp_extension_t::name
char * name
An optional extension name.
Definition: cpluff.h:650
CP_LOG_WARNING
@ CP_LOG_WARNING
Used for messages warning about possible problems.
Definition: cpluff.h:250
cp_plugin_info_t::provider_name
char * provider_name
An optional provider name.
Definition: cpluff.h:432
cp_get_version
const CP_IMPORT char * cp_get_version(void)
Returns the release version string of the linked in C-Pluff implementation.
cp_context_t
struct cp_context_t cp_context_t
A plug-in context represents the co-operation environment of a set of plug-ins from the perspective o...
Definition: cpluff.h:281
cp_unregister_pcollection
CP_IMPORT void cp_unregister_pcollection(cp_context_t *ctx, const char *dir)
Unregisters a previously registered plug-in collection from a plug-in context.
cp_log
CP_IMPORT void cp_log(cp_context_t *ctx, cp_log_severity_t severity, const char *msg)
Emits a new log message.
cp_define_symbol
CP_IMPORT cp_status_t cp_define_symbol(cp_context_t *ctx, const char *name, void *ptr)
Defines a context specific symbol.
cp_extension_t::ext_point_id
char * ext_point_id
The unique identifier of the extension point this extension is attached to.
Definition: cpluff.h:628
CP_PLUGIN_STARTING
@ CP_PLUGIN_STARTING
Plug-in is starting.
Definition: cpluff.h:213
cp_destroy
CP_IMPORT void cp_destroy(void)
Destroys the plug-in framework and releases the resources used by it.
cp_get_host_type
const CP_IMPORT char * cp_get_host_type(void)
Returns the canonical host type associated with the linked in C-Pluff implementation.
cp_cfg_element_t::num_children
unsigned int num_children
Number of children in the children array.
Definition: cpluff.h:701
cp_get_extensions_info
CP_IMPORT cp_extension_t ** cp_get_extensions_info(cp_context_t *ctx, const char *extpt_id, cp_status_t *status, int *num)
Returns static information about the currently installed extension points.
CP_GCC_PURE
#define CP_GCC_PURE
Definition: cpluffdef.h:190
cp_stop_plugin
CP_IMPORT cp_status_t cp_stop_plugin(cp_context_t *ctx, const char *id)
Stops a plug-in.
cp_plugin_info_t::extensions
cp_extension_t * extensions
An array of num_extensions extensions provided by this plug-in.
Definition: cpluff.h:524
cp_log_severity_t
cp_log_severity_t
Definition: cpluff.h:241
cp_plugin_info_t::abi_bw_compatibility
char * abi_bw_compatibility
Optional ABI compatibility information.
Definition: cpluff.h:454
CP_ERR_MALFORMED
@ CP_ERR_MALFORMED
Malformed plug-in descriptor was encountered when loading a plug-in.
Definition: cpluff.h:151
cp_resolve_symbol
CP_IMPORT void * cp_resolve_symbol(cp_context_t *ctx, const char *id, const char *name, cp_status_t *status)
Resolves a symbol provided by the specified plug-in.
CP_ERR_CONFLICT
@ CP_ERR_CONFLICT
Plug-in or symbol conflicts with another plug-in or symbol.
Definition: cpluff.h:154
cp_register_plistener
CP_IMPORT cp_status_t cp_register_plistener(cp_context_t *ctx, cp_plugin_listener_func_t listener, void *user_data)
Registers a plug-in listener with a plug-in context.
cp_plugin_state_t
cp_plugin_state_t
Definition: cpluff.h:175
cp_scan_plugins
CP_IMPORT cp_status_t cp_scan_plugins(cp_context_t *ctx, int flags)
Scans for plug-ins in the registered plug-in directories, installing new plug-ins and upgrading insta...
cp_load_plugin_descriptor_from_memory
CP_IMPORT cp_plugin_info_t * cp_load_plugin_descriptor_from_memory(cp_context_t *ctx, const char *buffer, unsigned int buffer_len, cp_status_t *status)
Loads a plug-in descriptor from the specified block of memory and returns information about the plug-...
cp_plugin_info_t::api_bw_compatibility
char * api_bw_compatibility
Optional API compatibility information.
Definition: cpluff.h:468
cp_plugin_info_t::runtime_funcs_symbol
char * runtime_funcs_symbol
The symbol pointing to the plug-in runtime function information or NULL if none.
Definition: cpluff.h:504
CP_PLUGIN_RESOLVED
@ CP_PLUGIN_RESOLVED
Plug-in dependencies have been resolved.
Definition: cpluff.h:202
cp_plugin_import_t::version
char * version
An optional version requirement.
Definition: cpluff.h:549
cp_start_plugin
CP_IMPORT cp_status_t cp_start_plugin(cp_context_t *ctx, const char *id)
Starts a plug-in.
cp_extension_t::local_id
char * local_id
An optional local identifier uniquely identifying the extension within the host plug-in.
Definition: cpluff.h:635
cp_plugin_listener_func_t
void(* cp_plugin_listener_func_t)(const char *plugin_id, cp_plugin_state_t old_state, cp_plugin_state_t new_state, void *user_data)
A listener function called synchronously after a plugin state change.
Definition: cpluff.h:347
cp_lpl_unregister_dirs
CP_IMPORT void cp_lpl_unregister_dirs(cp_plugin_loader_t *loader)
Unregisters all registered directories from the specified local plug-in loader.
cp_fatal_error_func_t
void(* cp_fatal_error_func_t)(const char *msg)
A fatal error handler for handling unrecoverable errors.
Definition: cpluff.h:372
cp_extension_t::configuration
cp_cfg_element_t * configuration
Extension configuration starting with the extension element.
Definition: cpluff.h:658
cp_unregister_logger
CP_IMPORT void cp_unregister_logger(cp_context_t *ctx, cp_logger_func_t logger)
Removes a logger registration.
cp_cfg_element_t
Definition: cpluff.h:670
cp_install_plugin
CP_IMPORT cp_status_t cp_install_plugin(cp_context_t *ctx, cp_plugin_info_t *pi)
Installs the plug-in described by the specified plug-in information structure to the specified plug-i...
cp_unregister_ploaders
CP_IMPORT void cp_unregister_ploaders(cp_context_t *ctx)
Unregisters all registered plug-in loaders from a plug-in context.
CP_C_API
#define CP_C_API
Definition: cpluff.h:61
CP_LOG_ERROR
@ CP_LOG_ERROR
Used for messages reporting errors.
Definition: cpluff.h:253
cp_plugin_runtime_t
Definition: cpluff.h:737
cp_cfg_element_t::index
unsigned int index
The index of this element among its siblings (0-based).
Definition: cpluff.h:698
cp_plugin_import_t::optional
int optional
Is this import optional.
Definition: cpluff.h:560
cpluffdef.h
cp_plugin_loader_t::release_plugins
void(* release_plugins)(void *data, cp_context_t *ctx, cp_plugin_info_t **plugins)
A function called to release plug-in information returned by the scan_plugins function.
Definition: cpluff.h:900
cp_plugin_import_t
Definition: cpluff.h:533
cp_cfg_element_t::value
char * value
An optional value of this configuration element.
Definition: cpluff.h:692
cp_lookup_cfg_value
CP_IMPORT char * cp_lookup_cfg_value(cp_cfg_element_t *base, const char *path)
Traverses a configuration element tree and returns the value of the specified element or attribute.
cp_plugin_loader_t::data
void * data
An opaque data pointer for this plug-in loader instance.
Definition: cpluff.h:847
cp_is_logged
CP_IMPORT int cp_is_logged(cp_context_t *ctx, cp_log_severity_t severity)
Returns whether a message of the specified severity would get logged.
cp_plugin_info_t::num_imports
unsigned int num_imports
Number of import entries in the imports array.
Definition: cpluff.h:481
cp_get_plugin_state
CP_IMPORT cp_plugin_state_t cp_get_plugin_state(cp_context_t *ctx, const char *id)
Returns the current state of the specified plug-in.
CP_ERR_RESOURCE
@ CP_ERR_RESOURCE
Not enough memory or other operating system resources available.
Definition: cpluff.h:142
cp_plugin_info_t::ext_points
cp_ext_point_t * ext_points
An array of num_ext_points extension points provided by this plug-in.
Definition: cpluff.h:514
cp_destroy_local_ploader
CP_IMPORT void cp_destroy_local_ploader(cp_plugin_loader_t *loader)
Releases the resources allocated by a previously created local plug-in loader.
cp_run_plugins
CP_IMPORT void cp_run_plugins(cp_context_t *ctx)
Runs the started plug-ins as long as there is something to run.
cp_plugin_info_t::version
char * version
An optional release version string.
Definition: cpluff.h:423
cp_cfg_element_t::parent
cp_cfg_element_t * parent
A pointer to the parent element or NULL if this is a root element.
Definition: cpluff.h:695
cp_plugin_info_t::runtime_lib_name
char * runtime_lib_name
The base name of the plug-in runtime library, or NULL if none.
Definition: cpluff.h:496
cp_unregister_ploader
CP_IMPORT void cp_unregister_ploader(cp_context_t *ctx, cp_plugin_loader_t *loader)
Unregisters a previously registered plug-in loader from a plug-in context.
cp_create_local_ploader
CP_IMPORT cp_plugin_loader_t * cp_create_local_ploader(cp_status_t *status)
Creates and returns a new instance of a local plug-in loader.
CP_GCC_NONNULL
#define CP_GCC_NONNULL(...)
Definition: cpluffdef.h:195
cp_release_info
CP_IMPORT void cp_release_info(cp_context_t *ctx, void *info)
Releases a previously obtained reference counted information object.
cp_set_plugin_descriptor_root_element
CP_IMPORT void cp_set_plugin_descriptor_root_element(cp_context_t *ctx, const char *root)
Changes the XML root element's name in plug-in descriptor.
cp_extension_t
Definition: cpluff.h:614
CP_ERR_RUNTIME
@ CP_ERR_RUNTIME
Plug-in runtime signaled an error.
Definition: cpluff.h:160
cp_extension_t::identifier
char * identifier
An optional unique identifier of the extension.
Definition: cpluff.h:642
cp_set_fatal_error_handler
CP_IMPORT void cp_set_fatal_error_handler(cp_fatal_error_func_t error_handler)
Sets the fatal error handler called on non-recoverable errors.
CP_PLUGIN_INSTALLED
@ CP_PLUGIN_INSTALLED
Plug-in is installed.
Definition: cpluff.h:190
cp_unregister_plistener
CP_IMPORT void cp_unregister_plistener(cp_context_t *ctx, cp_plugin_listener_func_t listener)
Removes a plug-in listener from a plug-in context.
cp_plugin_info_t
Definition: cpluff.h:399
CP_LOG_DEBUG
@ CP_LOG_DEBUG
Used for detailed debug messages.
Definition: cpluff.h:244
cp_lookup_cfg_element
CP_IMPORT cp_cfg_element_t * cp_lookup_cfg_element(cp_cfg_element_t *base, const char *path)
Traverses a configuration element tree and returns the specified element.
cp_uninstall_plugin
CP_IMPORT cp_status_t cp_uninstall_plugin(cp_context_t *ctx, const char *id)
Uninstalls the specified plug-in.
cp_plugin_runtime_t::destroy
void(* destroy)(void *data)
A destroy function called to destroy a plug-in instance.
Definition: cpluff.h:817
cp_ext_point_t::identifier
char * identifier
The unique identifier of the extension point.
Definition: cpluff.h:590
CP_PLUGIN_STOPPING
@ CP_PLUGIN_STOPPING
Plug-in is stopping.
Definition: cpluff.h:224

Generated on Sun May 3 2020 12:13:55 for C-Pluff C API by 1.8.17