# Plug-in management
[Functions]

## Detailed Description

These functions can be used to manage plug-ins.

They are intended to be used by the main program.

## Functions

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

## Function Documentation

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:

  | 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

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:

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

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

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

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

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

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

Stops all active plug-ins.

Parameters:

  | ctx | the plug-in context

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

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

Generated on Fri Apr 6 15:40:55 2007 for C-Pluff C API by 1.5.1