C-Pluff C API: Plug-in management

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

Plug-in management
[Functions]

Detailed Description

Functions

Function Documentation


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.

Plug-in management [Functions]

Detailed Description

Functions

Function Documentation

Plug-in management
[Functions]