Plug-in and extension information
[Functions]

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.


Functions

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.
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.
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.
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.
void cp_release_info (cp_context_t *ctx, void *info)
 Releases a previously obtained reference counted information object.
cp_plugin_state_t cp_get_plugin_state (cp_context_t *ctx, const char *id)
 Returns the current state of the specified plug-in.
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.
void cp_unregister_plistener (cp_context_t *ctx, cp_plugin_listener_func_t listener)
 Removes a plug-in listener from a plug-in context.
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.
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.

Function Documentation

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_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_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_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

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_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_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

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_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

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

C-Pluff, a plug-in framework for C
Copyright 2007 Johannes Lehtinen

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