# 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

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