C-Pluff C API  0.2.0
Functions
Plug-in management

These functions can be used to manage plug-ins. More...

Functions

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. More...
 
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. More...
 
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. More...
 
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. More...
 
CP_IMPORT cp_status_t cp_start_plugin (cp_context_t *ctx, const char *id)
 Starts a plug-in. More...
 
CP_IMPORT cp_status_t cp_stop_plugin (cp_context_t *ctx, const char *id)
 Stops a plug-in. More...
 
CP_IMPORT void cp_stop_plugins (cp_context_t *ctx)
 Stops all active plug-ins. More...
 
CP_IMPORT cp_status_t cp_uninstall_plugin (cp_context_t *ctx, const char *id)
 Uninstalls the specified plug-in. More...
 
CP_IMPORT void cp_uninstall_plugins (cp_context_t *ctx)
 Uninstalls all plug-ins. More...
 

Detailed Description

These functions can be used to manage plug-ins.

They are intended to be used by the main program.

Function Documentation

◆ 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

Generated on Fri May 1 2020 01:06:58 for C-Pluff C API by doxygen 1.8.13