C-Pluff C API  0.1.4
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_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_plugin_info when it does not need the information anymore, typically after installing the plug-in. The returned plug-in information must not be modified.

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_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_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_plugin_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_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_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_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_IMPORT void cp_stop_plugins ( cp_context_t ctx)

Stops all active plug-ins.

Parameters
ctxthe plug-in context
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_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 Jan 1 2016 23:17:02 for C-Pluff C API by doxygen 1.8.6