Plug-in and extension information

These functions can be used to query information about the installed plug-ins, extension points and extensions or to listen for plug-in state changes. More...

Functions
CP_IMPORT cp_plugin_info_t *	cp_get_plugin_info (cp_context_t *ctx, const char *id, cp_status_t *status)
	Returns static information about the specified plug-in. More...
CP_IMPORT cp_plugin_info_t **	cp_get_plugins_info (cp_context_t *ctx, cp_status_t *status, int *num)
	Returns static information about the installed plug-ins. More...
CP_IMPORT cp_ext_point_t **	cp_get_ext_points_info (cp_context_t *ctx, cp_status_t *status, int *num)
	Returns static information about the currently installed extension points. More...
CP_IMPORT cp_extension_t **	cp_get_extensions_info (cp_context_t *ctx, const char *extpt_id, cp_status_t *status, int *num)
	Returns static information about the currently installed extension points. More...
CP_IMPORT void	cp_release_info (cp_context_t *ctx, void *info)
	Releases a previously obtained reference counted information object. More...
CP_IMPORT cp_plugin_state_t	cp_get_plugin_state (cp_context_t *ctx, const char *id)
	Returns the current state of the specified plug-in. More...
CP_IMPORT cp_status_t	cp_register_plistener (cp_context_t *ctx, cp_plugin_listener_func_t listener, void *user_data)
	Registers a plug-in listener with a plug-in context. More...
CP_IMPORT void	cp_unregister_plistener (cp_context_t *ctx, cp_plugin_listener_func_t listener)
	Removes a plug-in listener from a plug-in context. More...
CP_IMPORT cp_cfg_element_t *	cp_lookup_cfg_element (cp_cfg_element_t *base, const char *path)
	Traverses a configuration element tree and returns the specified element. More...
CP_IMPORT char *	cp_lookup_cfg_value (cp_cfg_element_t *base, const char *path)
	Traverses a configuration element tree and returns the value of the specified element or attribute. More...

Detailed Description

These functions can be used to query information about the installed plug-ins, extension points and extensions or to listen for plug-in state changes.

They may be used by the main program or by a plug-in runtime.

Function Documentation

cp_get_plugin_info()

CP_IMPORT cp_plugin_info_t* cp_get_plugin_info	(	cp_context_t *	ctx,
		const char *	id,
		cp_status_t *	status
	)

Returns static information about the specified plug-in.

The returned information must not be modified and the caller must release the information by calling cp_release_info when the information is not needed anymore. When a plug-in runtime calls this function it may pass NULL as the identifier to get information about the plug-in itself.

Parameters

ctx	the plug-in context
id	identifier of the plug-in to be examined or NULL for self
status	a pointer to the location where status code is to be stored, or NULL

Returns

pointer to the information structure or NULL on failure

cp_get_plugins_info()

CP_IMPORT cp_plugin_info_t** cp_get_plugins_info	(	cp_context_t *	ctx,
		cp_status_t *	status,
		int *	num
	)

Returns static information about the installed plug-ins.

The returned information must not be modified and the caller must release the information by calling cp_release_info when the information is not needed anymore.

Parameters

ctx	the plug-in context
status	a pointer to the location where status code is to be stored, or NULL
num	a pointer to the location where the number of returned plug-ins is stored, or NULL

Returns

pointer to a NULL-terminated list of pointers to plug-in information or NULL on failure

cp_get_ext_points_info()

CP_IMPORT cp_ext_point_t** cp_get_ext_points_info	(	cp_context_t *	ctx,
		cp_status_t *	status,
		int *	num
	)

Returns static information about the currently installed extension points.

The returned information must not be modified and the caller must release the information by calling cp_release_info when the information is not needed anymore.

Parameters

ctx	the plug-in context
status	a pointer to the location where status code is to be stored, or NULL
num	filled with the number of returned extension points, if non-NULL

Returns

pointer to a NULL-terminated list of pointers to extension point information or NULL on failure

cp_get_extensions_info()

CP_IMPORT cp_extension_t** cp_get_extensions_info	(	cp_context_t *	ctx,
		const char *	extpt_id,
		cp_status_t *	status,
		int *	num
	)

Returns static information about the currently installed extension points.

The returned information must not be modified and the caller must release the information by calling cp_release_info when the information is not needed anymore.

Parameters

ctx	the plug-in context
extpt_id	the extension point identifier or NULL for all extensions
status	a pointer to the location where status code is to be stored, or NULL
num	a pointer to the location where the number of returned extension points is to be stored, or NULL

Returns

pointer to a NULL-terminated list of pointers to extension information or NULL on failure

cp_release_info()

CP_IMPORT void cp_release_info	(	cp_context_t *	ctx,
		void *	info
	)

Releases a previously obtained reference counted information object.

The documentation for functions returning such information refers to this function. The information must not be accessed after it has been released. The framework uses reference counting to deallocate the information when it is not in use anymore.

Parameters

ctx	the plug-in context
info	the information to be released

cp_get_plugin_state()

CP_IMPORT cp_plugin_state_t cp_get_plugin_state	(	cp_context_t *	ctx,
		const char *	id
	)

Returns the current state of the specified plug-in.

Returns CP_PLUGIN_UNINSTALLED if the specified plug-in identifier is unknown.

Parameters

ctx	the plug-in context
id	the plug-in identifier

Returns

the current state of the plug-in

cp_register_plistener()

CP_IMPORT cp_status_t cp_register_plistener	(	cp_context_t *	ctx,
		cp_plugin_listener_func_t	listener,
		void *	user_data
	)

Registers a plug-in listener with a plug-in context.

The listener is called synchronously immediately after a plug-in state change. There can be several listeners registered with the same context. A plug-in listener can be unregistered using cp_unregister_plistener and it is automatically unregistered when the registering plug-in is stopped or when the context is destroyed.

Parameters

ctx	the plug-in context
listener	the plug-in listener to be added
user_data	user data pointer supplied to the listener

Returns

CP_OK (zero) on success or CP_ERR_RESOURCE if out of resources

cp_unregister_plistener()

CP_IMPORT void cp_unregister_plistener	(	cp_context_t *	ctx,
		cp_plugin_listener_func_t	listener
	)

Removes a plug-in listener from a plug-in context.

Does nothing if the specified listener was not registered.

Parameters

ctx	the plug-in context
listener	the plug-in listener to be removed

cp_lookup_cfg_element()

CP_IMPORT cp_cfg_element_t* cp_lookup_cfg_element	(	cp_cfg_element_t *	base,
		const char *	path
	)

Traverses a configuration element tree and returns the specified element.

The target element is specified by a base element and a relative path from the base element to the target element. The path includes element names separated by slash '/'. Two dots ".." can be used to designate a parent element. Returns NULL if the specified element does not exist. If there are several subelements with the same name, this function chooses the first one when traversing the tree.

Parameters

base	the base configuration element
path	the path to the target element

Returns

the target element or NULL if nonexisting

cp_lookup_cfg_value()

CP_IMPORT char* cp_lookup_cfg_value	(	cp_cfg_element_t *	base,
		const char *	path
	)

Traverses a configuration element tree and returns the value of the specified element or attribute.

The target element or attribute is specified by a base element and a relative path from the base element to the target element or attributes. The path includes element names separated by slash '/'. Two dots ".." can be used to designate a parent element. The path may end with '@' followed by an attribute name to select an attribute. Returns NULL if the specified element or attribute does not exist or does not have a value. If there are several subelements with the same name, this function chooses the first one when traversing the tree.

Parameters

base	the base configuration element
path	the path to the target element

Returns

the value of the target element or attribute or NULL