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_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_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_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.
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.
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_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_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_t * | cp_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_t * | cp_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 create.

## cp_plugin_info_t

typedef struct cp_plugin_info_t cp_plugin_info_t

A type for cp_plugin_info_t structure.

## cp_plugin_import_t

typedef struct cp_plugin_import_t cp_plugin_import_t

A type for cp_plugin_import_t structure.

## cp_ext_point_t

typedef struct cp_ext_point_t cp_ext_point_t

A type for cp_ext_point_t structure.

## cp_extension_t

typedef struct cp_extension_t cp_extension_t

A type for cp_extension_t structure.

## cp_cfg_element_t

typedef struct cp_cfg_element_t cp_cfg_element_t

A type for cp_cfg_element_t structure.

## cp_plugin_runtime_t

typedef struct cp_plugin_runtime_t cp_plugin_runtime_t

A type for cp_plugin_runtime_t structure.

## cp_plugin_loader_t

typedef struct cp_plugin_loader_t 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

typedef enum cp_plugin_state_t cp_plugin_state_t

A type for cp_plugin_state_t enumeration.

## cp_log_severity_t

typedef enum cp_log_severity_t 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_id | the plug-in identifier
  old_state | the old plug-in state
  new_state | the new plug-in state
  user_data | the 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

  severity | the severity of the message
  msg | the message to be logged, possibly localized
  apid | the identifier of the activating plug-in or NULL for the main program
  user_data | the 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

  msg | the 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_data | the 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

References CP_C_API, and CP_GCC_PURE.

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

References CP_C_API, and CP_GCC_PURE.

## 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_handler | the fatal error handler

References CP_C_API.

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

References CP_C_API.

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

References CP_C_API.

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

  status | pointer to the location where status code is to be stored, or NULL

Returns
  the newly created plugin context, or NULL on failure

References CP_C_API.

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

  ctx | the context to change the plug-in descriptor file name in
  name | the new plug-in descriptor file name

References CP_C_API.

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

  ctx | the context to change the plug-in descriptor's XML root element's name in
  root | the new XML root element name

References CP_C_API.

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

  ctx | the context to be destroyed

References CP_C_API.

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

  ctx | the plug-in context
  dir | the directory

Returns
  CP_OK (zero) on success or CP_ERR_RESOURCE if insufficient memory

References CP_C_API.

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

  ctx | the plug-in context
  dir | the previously registered directory

References CP_C_API.

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

  ctx | the plug-in context

References CP_C_API.

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

  ctx | the plug-in context
  loader | the plug-in loader

Returns
  CP_OK (zero) on success or CP_ERR_RESOURCE if insufficient memory

References CP_C_API.

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

  ctx | the plug-in context
  loader | the plug-in loader

References CP_C_API.

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

  ctx | the plug-in context

References CP_C_API.

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

  ctx | the plug-in context to log
  logger | the logger function to be called
  user_data | the user data pointer passed to the logger
  min_severity | the minimum severity of messages passed to logger

Returns
  CP_OK (zero) on success or CP_ERR_RESOURCE if insufficient memory

References CP_C_API.

## cp_unregister_logger()

CP_IMPORT void cp_unregister_logger | ( | cp_context_t * | ctx,
|  | cp_logger_func_t | logger )

Removes a logger registration.

Parameters

  ctx | the plug-in context
  logger | the logger function to be unregistered

References CP_C_API.

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

  ctx | the plug-in context
  severity | the severity of the event
  msg | the log message (possibly localized)

References CP_C_API.

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

  ctx | the plug-in context
  severity | the target logging severity

Returns
  whether a message of the specified severity would get logged

References CP_C_API.

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

  ctx | the plug-in context
  path | the installation path of the plug-in
  status | a pointer to the location where status code is to be stored, or NULL

Returns
  pointer to the information structure or NULL if error occurs

References CP_C_API.

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

  ctx | the plug-in context
  buffer | the buffer containing the plug-in descriptor.
  buffer_len | the length of the buffer.
  status | a pointer to the location where status code is to be stored, or NULL

Returns
  pointer to the information structure or NULL if error occurs

References CP_C_API.

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

  ctx | the plug-in context
  pi | plug-in information structure

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

References CP_C_API.

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

  ctx | the plug-in context
  flags | the bitmask of flags

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

References CP_C_API.

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

  ctx | the plug-in context
  id | identifier of the plug-in to be started

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

References CP_C_API.

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

  ctx | the plug-in context
  id | identifier of the plug-in to be stopped

Returns
  CP_OK (zero) on success or CP_ERR_UNKNOWN if unknown plug-in

References CP_C_API.

## cp_stop_plugins()

CP_IMPORT void cp_stop_plugins | ( | cp_context_t * | ctx | ) |

Stops all active plug-ins.

Parameters

  ctx | the plug-in context

References CP_C_API.

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

  ctx | the plug-in context
  id | identifier of the plug-in to be unloaded

Returns
  CP_OK (zero) on success or CP_ERR_UNKNOWN if unknown plug-in

References CP_C_API.

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

  ctx | the plug-in context

References CP_C_API.

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

  ctx | the plug-in context
  id | identifier of the plug-in to be examined or NULL for self
  status | a pointer to the location where status code is to be stored, or NULL

Returns
  pointer to the information structure or NULL on failure

References CP_C_API.

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

  ctx | the plug-in context
  status | a pointer to the location where status code is to be stored, or NULL
  num | a 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

References CP_C_API.

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

  ctx | the plug-in context
  status | a pointer to the location where status code is to be stored, or NULL
  num | filled 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

References CP_C_API.

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

  ctx | the plug-in context
  extpt_id | the extension point identifier or NULL for all extensions
  status | a pointer to the location where status code is to be stored, or NULL
  num | a 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

References CP_C_API.

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

  ctx | the plug-in context
  info | the information to be released

References CP_C_API.

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

  ctx | the plug-in context
  id | the plug-in identifier

Returns
  the current state of the plug-in

References CP_C_API.

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

  ctx | the plug-in context
  listener | the plug-in listener to be added
  user_data | user data pointer supplied to the listener

Returns
  CP_OK (zero) on success or CP_ERR_RESOURCE if out of resources

References CP_C_API.

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

  ctx | the plug-in context
  listener | the plug-in listener to be removed

References CP_C_API.

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

  base | the base configuration element
  path | the path to the target element

Returns
  the target element or NULL if nonexisting

References CP_C_API, and CP_GCC_PURE.

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

  base | the base configuration element
  path | the path to the target element

Returns
  the value of the target element or attribute or NULL

References CP_C_API, and CP_GCC_PURE.

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

  ctx | the plug-in context of the registering plug-in
  runfunc | the run function to be registered

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

References CP_C_API.

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

  ctx | the plug-in context containing the plug-ins

References CP_C_API.

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

  ctx | the plug-in context containing the plug-ins

Returns
  whether there are active run functions waiting to be run

References CP_C_API.

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

  ctx | the plug-in context
  argv | a NULL-terminated array of arguments

References CP_C_API.

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

  ctx | the plug-in context
  argc | a 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

References CP_C_API.

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

  ctx | the plug-in context
  name | the name of the symbol
  ptr | pointer value for the symbol

Returns
  CP_OK (zero) on success or a status code on failure

References CP_C_API.

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

  ctx | the plug-in context
  id | the identifier of the symbol defining plug-in
  name | the name of the symbol
  status | a 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

References CP_C_API.

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

  ctx | the plug-in context
  ptr | the pointer associated with the symbol

References CP_C_API.

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

  status | pointer to the location where status code is to be stored, or NULL

Returns
  the new plug-in loader instance, or NULL on failure

References CP_C_API.

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

  the | plug-in loader to be destroyed

References CP_C_API.

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

  loader | the plug-in loader obtained from cp_create_local_ploader
  dir | the directory to register

Returns
  CP_OK (zero) on success or CP_ERR_RESOURCE if insufficient memory

References CP_C_API.

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

  loader | the plug-in loader obtained from cp_create_local_ploader
  dir | the directory to unregister

References CP_C_API.

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

  loader | the plug-in

References CP_C_API.

Generated on for C-Pluff C API by 1.15.0