C-Pluff C API 0.2.0
Data Structures | Macros | Typedefs | Enumerations | Functions
cpluff.h File Reference

C-Pluff C API header file. More...

Include dependency graph for cpluff.h:

Go to the source code of this file.

Data Structures

struct  cp_plugin_info_t
 Plug-in information structure captures information about a plug-in. More...
 
struct  cp_plugin_import_t
 Information about plug-in import. More...
 
struct  cp_ext_point_t
 Extension point structure captures information about an extension point. More...
 
struct  cp_extension_t
 Extension structure captures information about an extension. More...
 
struct  cp_cfg_element_t
 A configuration element contains configuration information for an extension. More...
 
struct  cp_plugin_runtime_t
 Container for plug-in runtime information. More...
 
struct  cp_plugin_loader_t
 A plug-in loader instance. More...
 

Macros

#define CP_C_API
 Marks a symbol declaration to be part of the C-Pluff C API.
 
#define CP_SP_UPGRADE
 This flag enables upgrades of installed plug-ins by unloading the old version and installing the new version.
 
#define CP_SP_STOP_ALL_ON_UPGRADE
 This flag causes all plug-ins to be stopped before any plug-ins are to be upgraded.
 
#define CP_SP_STOP_ALL_ON_INSTALL
 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_RESTART_ACTIVE
 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).
 

Typedefs

typedef 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 of a particular participating plug-in or the perspective of the main program.
 
typedef struct cp_plugin_info_t cp_plugin_info_t
 A type for cp_plugin_info_t structure.
 
typedef struct cp_plugin_import_t cp_plugin_import_t
 A type for cp_plugin_import_t structure.
 
typedef struct cp_ext_point_t cp_ext_point_t
 A type for cp_ext_point_t structure.
 
typedef struct cp_extension_t cp_extension_t
 A type for cp_extension_t structure.
 
typedef struct cp_cfg_element_t cp_cfg_element_t
 A type for cp_cfg_element_t structure.
 
typedef struct cp_plugin_runtime_t cp_plugin_runtime_t
 A type for cp_plugin_runtime_t structure.
 
typedef struct cp_plugin_loader_t cp_plugin_loader_t
 A type for cp_plugin_loader_t structure.
 
typedef enum cp_status_t cp_status_t
 A type for cp_status_t enumeration.
 
typedef enum cp_plugin_state_t cp_plugin_state_t
 A type for cp_plugin_state_t enumeration.
 
typedef enum cp_log_severity_t cp_log_severity_t
 A type for cp_log_severity_t enumeration.
 
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 listener function called synchronously after a plugin state change.
 
typedef 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.
 
typedef void(* cp_fatal_error_func_t) (const char *msg)
 A fatal error handler for handling unrecoverable errors.
 
typedef int(* cp_run_func_t) (void *plugin_data)
 A run function registered by a plug-in to perform work.
 

Enumerations

enum  cp_status_t {
  CP_OK = 0 , CP_ERR_RESOURCE , CP_ERR_UNKNOWN , CP_ERR_IO ,
  CP_ERR_MALFORMED , CP_ERR_CONFLICT , CP_ERR_DEPENDENCY , CP_ERR_RUNTIME
}
 An enumeration of status codes returned by API functions. More...
 
enum  cp_plugin_state_t {
  CP_PLUGIN_UNINSTALLED , CP_PLUGIN_INSTALLED , CP_PLUGIN_RESOLVED , CP_PLUGIN_STARTING ,
  CP_PLUGIN_STOPPING , CP_PLUGIN_ACTIVE
}
 An enumeration of possible plug-in states. More...
 
enum  cp_log_severity_t { CP_LOG_DEBUG , CP_LOG_INFO , CP_LOG_WARNING , CP_LOG_ERROR }
 An enumeration of possible message severities for framework logging. More...
 

Functions

CP_IMPORT const char * cp_get_version (void)
 Returns the release version string of the linked in C-Pluff implementation.
 
CP_IMPORT const char * cp_get_host_type (void)
 Returns the canonical host type associated with the linked in C-Pluff implementation.
 
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_IMPORT cp_status_t cp_init (void)
 Initializes the plug-in framework.
 
CP_IMPORT void cp_destroy (void)
 Destroys the plug-in framework and releases the resources used by it.
 
CP_IMPORT cp_context_tcp_create_context (cp_status_t *status)
 Creates a new plug-in context which can be used as a container for plug-ins.
 
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_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_IMPORT void cp_destroy_context (cp_context_t *ctx)
 Destroys the specified plug-in context and releases the associated resources.
 
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_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_IMPORT void cp_unregister_pcollections (cp_context_t *ctx)
 Unregisters all plug-in collections from a plug-in context.
 
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 is called.
 
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_IMPORT void cp_unregister_ploaders (cp_context_t *ctx)
 Unregisters all registered plug-in loaders from a plug-in context.
 
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_IMPORT void cp_unregister_logger (cp_context_t *ctx, cp_logger_func_t logger)
 Removes a logger registration.
 
CP_IMPORT void cp_log (cp_context_t *ctx, cp_log_severity_t severity, const char *msg)
 Emits a new log message.
 
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_IMPORT cp_plugin_info_tcp_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 the plug-in.
 
CP_IMPORT cp_plugin_info_tcp_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-in.
 
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-in context.
 
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 installed plug-ins.
 
CP_IMPORT cp_status_t cp_start_plugin (cp_context_t *ctx, const char *id)
 Starts a plug-in.
 
CP_IMPORT cp_status_t cp_stop_plugin (cp_context_t *ctx, const char *id)
 Stops a plug-in.
 
CP_IMPORT void cp_stop_plugins (cp_context_t *ctx)
 Stops all active plug-ins.
 
CP_IMPORT cp_status_t cp_uninstall_plugin (cp_context_t *ctx, const char *id)
 Uninstalls the specified plug-in.
 
CP_IMPORT void cp_uninstall_plugins (cp_context_t *ctx)
 Uninstalls all plug-ins.
 
CP_IMPORT cp_plugin_info_tcp_get_plugin_info (cp_context_t *ctx, const char *id, cp_status_t *status)
 Returns static information about the specified plug-in.
 
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_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_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_IMPORT void cp_release_info (cp_context_t *ctx, void *info)
 Releases a previously obtained reference counted information object.
 
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_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_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_IMPORT cp_cfg_element_tcp_lookup_cfg_element (cp_cfg_element_t *base, const char *path)
 Traverses a configuration element tree and returns the specified element.
 
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_IMPORT cp_status_t cp_run_function (cp_context_t *ctx, cp_run_func_t runfunc)
 Registers a new run function.
 
CP_IMPORT void cp_run_plugins (cp_context_t *ctx)
 Runs the started plug-ins as long as there is something to run.
 
CP_IMPORT int cp_run_plugins_step (cp_context_t *ctx)
 Runs one registered run function.
 
CP_IMPORT void cp_set_context_args (cp_context_t *ctx, char **argv)
 Sets startup arguments for the specified plug-in context.
 
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_IMPORT cp_status_t cp_define_symbol (cp_context_t *ctx, const char *name, void *ptr)
 Defines a context specific 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_IMPORT void cp_release_symbol (cp_context_t *ctx, const void *ptr)
 Releases a previously obtained symbol.
 
CP_IMPORT cp_plugin_loader_tcp_create_local_ploader (cp_status_t *status)
 Creates and returns a new instance of a local plug-in loader.
 
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_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_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_IMPORT void cp_lpl_unregister_dirs (cp_plugin_loader_t *loader)
 Unregisters all registered directories from the specified local plug-in loader.
 

Detailed Description

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.

Macro Definition Documentation

◆ CP_SP_UPGRADE

#define CP_SP_UPGRADE

This flag enables upgrades of installed plug-ins by unloading the old version and installing the new version.

◆ CP_SP_STOP_ALL_ON_UPGRADE

#define CP_SP_STOP_ALL_ON_UPGRADE

This flag causes all plug-ins to be stopped before any plug-ins are to be upgraded.

◆ CP_SP_STOP_ALL_ON_INSTALL

#define CP_SP_STOP_ALL_ON_INSTALL

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).

◆ CP_SP_RESTART_ACTIVE

#define CP_SP_RESTART_ACTIVE

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).

Typedef Documentation

◆ cp_context_t

typedef 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 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 cp_plugin_runtime_t::create.

◆ cp_plugin_info_t

A type for cp_plugin_info_t structure.

◆ cp_plugin_import_t

A type for cp_plugin_import_t structure.

◆ cp_ext_point_t

A type for cp_ext_point_t structure.

◆ cp_extension_t

A type for cp_extension_t structure.

◆ cp_cfg_element_t

A type for cp_cfg_element_t structure.

◆ cp_plugin_runtime_t

A type for cp_plugin_runtime_t structure.

◆ cp_plugin_loader_t

A type for cp_plugin_loader_t structure.

◆ cp_status_t

typedef enum cp_status_t cp_status_t

A type for cp_status_t enumeration.

◆ cp_plugin_state_t

A type for cp_plugin_state_t enumeration.

◆ cp_log_severity_t

A type for cp_log_severity_t enumeration.

◆ cp_plugin_listener_func_t

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 listener function called synchronously after a plugin state change.

The function should return promptly. Library initialization, plug-in context management, plug-in management, listener registration (cp_register_plistener and cp_unregister_plistener) and dynamic symbol functions must not be called from within a plug-in listener invocation. Listener functions are registered using cp_register_plistener.

Parameters
plugin_idthe plug-in identifier
old_statethe old plug-in state
new_statethe new plug-in state
user_datathe user data pointer supplied at listener registration

◆ cp_logger_func_t

typedef 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.

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.

Parameters
severitythe severity of the message
msgthe message to be logged, possibly localized
apidthe identifier of the activating plug-in or NULL for the main program
user_datathe user data pointer given when the logger was registered

◆ cp_fatal_error_func_t

typedef void(* cp_fatal_error_func_t) (const char *msg)

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.

Parameters
msgthe possibly localized error message

◆ cp_run_func_t

typedef int(* cp_run_func_t) (void *plugin_data)

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 serial execution section.

Parameters
plugin_datathe plug-in instance data pointer
Returns
non-zero if there is more work to be done or zero if finished

Function Documentation

◆ cp_get_version()

CP_IMPORT const char * cp_get_version ( void  )

Returns the release version string of the linked in C-Pluff implementation.

Returns
the C-Pluff release version string

◆ cp_get_host_type()

CP_IMPORT const char * cp_get_host_type ( void  )

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.

Returns
the canonical host type

◆ 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.

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.

Parameters
error_handlerthe fatal error handler

◆ cp_init()

CP_IMPORT cp_status_t cp_init ( void  )

Initializes the plug-in framework.

This function must be called by the main program before calling any other plug-in framework functions except 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

setlocale(LC_ALL, "")

before calling this function.

Returns
CP_OK (zero) on success or error code on failure

◆ cp_destroy()

CP_IMPORT void cp_destroy ( 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_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.

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.

Parameters
statuspointer to the location where status code is to be stored, or NULL
Returns
the newly created plugin context, or NULL on failure

◆ 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.

The default name is "plugin.xml"

Parameters
ctxthe context to change the plug-in descriptor file name in
namethe new plug-in descriptor file name

◆ 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.

This also changes the attribute name to be used in the "import" element. The default name is "plugin".

Parameters
ctxthe context to change the plug-in descriptor's XML root element's name in
rootthe new XML root element name

◆ cp_destroy_context()

CP_IMPORT void cp_destroy_context ( cp_context_t ctx)

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.

Parameters
ctxthe context to be destroyed

◆ 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.

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

Parameters
ctxthe plug-in context
dirthe directory
Returns
CP_OK (zero) on success or CP_ERR_RESOURCE if insufficient memory

◆ 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.

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.

Parameters
ctxthe plug-in context
dirthe previously registered directory

◆ cp_unregister_pcollections()

CP_IMPORT void cp_unregister_pcollections ( cp_context_t ctx)

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.

Parameters
ctxthe plug-in context

◆ 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 is called.

Several plug-in loaders can be registered for a context. Returns 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

Parameters
ctxthe plug-in context
loaderthe plug-in loader
Returns
CP_OK (zero) on success or CP_ERR_RESOURCE if insufficient memory

◆ 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.

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.

Parameters
ctxthe plug-in context
loaderthe plug-in loader

◆ cp_unregister_ploaders()

CP_IMPORT void cp_unregister_ploaders ( cp_context_t ctx)

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.

Parameters
ctxthe plug-in context

◆ 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.

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.

Parameters
ctxthe plug-in context to log
loggerthe logger function to be called
user_datathe user data pointer passed to the logger
min_severitythe minimum severity of messages passed to logger
Returns
CP_OK (zero) on success or CP_ERR_RESOURCE if insufficient memory

◆ cp_unregister_logger()

CP_IMPORT void cp_unregister_logger ( cp_context_t ctx,
cp_logger_func_t  logger 
)

Removes a logger registration.

Parameters
ctxthe plug-in context
loggerthe logger function to be unregistered

◆ cp_log()

CP_IMPORT void cp_log ( cp_context_t ctx,
cp_log_severity_t  severity,
const char *  msg 
)

Emits a new log message.

Parameters
ctxthe plug-in context
severitythe severity of the event
msgthe log message (possibly localized)

◆ 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.

Parameters
ctxthe plug-in context
severitythe target logging severity
Returns
whether a message of the specified severity would get logged

◆ 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 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.

Parameters
ctxthe plug-in context
paththe installation path of the plug-in
statusa pointer to the location where status code is to be stored, or NULL
Returns
pointer to the information structure or NULL if error occurs

◆ 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-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.

Parameters
ctxthe plug-in context
bufferthe buffer containing the plug-in descriptor.
buffer_lenthe length of the buffer.
statusa pointer to the location where status code is to be stored, or NULL
Returns
pointer to the information structure or NULL if error occurs

◆ 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-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.

Parameters
ctxthe plug-in context
piplug-in information structure
Returns
CP_OK (zero) on success or an error code on failure

◆ 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 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 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.

Parameters
ctxthe plug-in context
flagsthe bitmask of flags
Returns
CP_OK (zero) on success or an error code on failure

◆ cp_start_plugin()

CP_IMPORT cp_status_t cp_start_plugin ( cp_context_t ctx,
const char *  id 
)

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.

Parameters
ctxthe plug-in context
ididentifier of the plug-in to be started
Returns
CP_OK (zero) on success or an error code on failure

◆ cp_stop_plugin()

CP_IMPORT cp_status_t cp_stop_plugin ( cp_context_t ctx,
const char *  id 
)

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.

Parameters
ctxthe plug-in context
ididentifier of the plug-in to be stopped
Returns
CP_OK (zero) on success or CP_ERR_UNKNOWN if unknown plug-in

◆ cp_stop_plugins()

CP_IMPORT void cp_stop_plugins ( cp_context_t ctx)

Stops all active plug-ins.

Parameters
ctxthe plug-in context

◆ cp_uninstall_plugin()

CP_IMPORT cp_status_t cp_uninstall_plugin ( cp_context_t ctx,
const char *  id 
)

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.

Parameters
ctxthe plug-in context
ididentifier of the plug-in to be unloaded
Returns
CP_OK (zero) on success or CP_ERR_UNKNOWN if unknown plug-in

◆ cp_uninstall_plugins()

CP_IMPORT void cp_uninstall_plugins ( cp_context_t ctx)

Uninstalls all plug-ins.

All plug-ins are first stopped and then uninstalled.

Parameters
ctxthe plug-in context

◆ 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.

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.

Parameters
ctxthe plug-in context
ididentifier of the plug-in to be examined or NULL for self
statusa pointer to the location where status code is to be stored, or NULL
Returns
pointer to the information structure or NULL on failure

◆ 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.

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.

Parameters
ctxthe plug-in context
statusa pointer to the location where status code is to be stored, or NULL
numa pointer to the location where the number of returned plug-ins is stored, or NULL
Returns
pointer to a NULL-terminated list of pointers to plug-in information or NULL on failure

◆ 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.

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.

Parameters
ctxthe plug-in context
statusa pointer to the location where status code is to be stored, or NULL
numfilled with the number of returned extension points, if non-NULL
Returns
pointer to a NULL-terminated list of pointers to extension point information or NULL on failure

◆ 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.

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.

Parameters
ctxthe plug-in context
extpt_idthe extension point identifier or NULL for all extensions
statusa pointer to the location where status code is to be stored, or NULL
numa pointer to the location where the number of returned extension points is to be stored, or NULL
Returns
pointer to a NULL-terminated list of pointers to extension information or NULL on failure

◆ cp_release_info()

CP_IMPORT void cp_release_info ( cp_context_t ctx,
void *  info 
)

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.

Parameters
ctxthe plug-in context
infothe information to be released

◆ 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.

Returns CP_PLUGIN_UNINSTALLED if the specified plug-in identifier is unknown.

Parameters
ctxthe plug-in context
idthe plug-in identifier
Returns
the current state of the plug-in

◆ 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.

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.

Parameters
ctxthe plug-in context
listenerthe plug-in listener to be added
user_datauser data pointer supplied to the listener
Returns
CP_OK (zero) on success or CP_ERR_RESOURCE if out of resources

◆ 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.

Does nothing if the specified listener was not registered.

Parameters
ctxthe plug-in context
listenerthe plug-in listener to be removed

◆ 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.

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.

Parameters
basethe base configuration element
paththe path to the target element
Returns
the target element or NULL if nonexisting

◆ 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.

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.

Parameters
basethe base configuration element
paththe path to the target element
Returns
the value of the target element or attribute or NULL

◆ 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.

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.

Parameters
ctxthe plug-in context of the registering plug-in
runfuncthe run function to be registered
Returns
CP_OK (zero) on success or an error code on failure

◆ 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.

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.

Parameters
ctxthe plug-in context containing the plug-ins

◆ cp_run_plugins_step()

CP_IMPORT int cp_run_plugins_step ( cp_context_t ctx)

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.

Parameters
ctxthe plug-in context containing the plug-ins
Returns
whether there are active run functions waiting to be run

◆ 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.

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.

Parameters
ctxthe plug-in context
argva NULL-terminated array of arguments

◆ 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.

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.

Parameters
ctxthe plug-in context
argca pointer to a location where the number of startup arguments is stored, or NULL for none
Returns
an argument array terminated by NULL or NULL if not set

◆ 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.

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.

Parameters
ctxthe plug-in context
namethe name of the symbol
ptrpointer value for the symbol
Returns
CP_OK (zero) on success or a status code on failure

◆ 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.

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.

Parameters
ctxthe plug-in context
idthe identifier of the symbol defining plug-in
namethe name of the symbol
statusa pointer to the location where the status code is to be stored, or NULL
Returns
the pointer associated with the symbol or NULL on failure

◆ cp_release_symbol()

CP_IMPORT void cp_release_symbol ( cp_context_t ctx,
const void *  ptr 
)

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.

Parameters
ctxthe plug-in context
ptrthe pointer associated with the symbol

◆ 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.

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.

Parameters
statuspointer to the location where status code is to be stored, or NULL
Returns
the new plug-in loader instance, or NULL on failure

◆ 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.

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.

Parameters
theplug-in loader to be destroyed

◆ 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.

Returns CP_OK if the directory has already been registered.

Parameters
loaderthe plug-in loader obtained from cp_create_local_ploader
dirthe directory to register
Returns
CP_OK (zero) on success or CP_ERR_RESOURCE if insufficient memory

◆ 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.

Does nothing if the specified directory has not been registered. This does not affect the status of already loaded plug-ins.

Parameters
loaderthe plug-in loader obtained from cp_create_local_ploader
dirthe directory to unregister

◆ 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.

This does not affect the status of already loaded plug-ins.

Parameters
loaderthe plug-in

Generated on Sun Mar 31 2024 17:56:45 for C-Pluff C API by doxygen 1.9.8