Plug-in context initialization

These functions are used to manage plug-in contexts from the main program perspective. More...

Functions
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. More...
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. More...
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. More...
CP_IMPORT void	cp_destroy_context (cp_context_t *ctx)
	Destroys the specified plug-in context and releases the associated resources. More...
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. More...
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. More...
CP_IMPORT void	cp_unregister_pcollections (cp_context_t *ctx)
	Unregisters all plug-in collections from a plug-in context. More...
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. More...
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. More...
CP_IMPORT void	cp_unregister_ploaders (cp_context_t *ctx)
	Unregisters all registered plug-in loaders from a plug-in context. More...

Detailed Description

These functions are used to manage plug-in contexts from the main program perspective.

They are not intended to be used by a plug-in runtime. From the main program perspective a plug-in context is a container for installed plug-ins. There can be several plug-in context instances if there are several independent sets of plug-ins. However, different plug-in contexts are not very isolated from each other in practice because the global symbols exported by a plug-in runtime in one context are visible to all plug-ins in all context instances.

Function Documentation

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

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

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

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

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

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

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

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

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

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