# Plug-in context initialization
[Functions]

## 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.

## Functions

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.
void | cp_destroy_context (cp_context_t *ctx)
| Destroys the specified plug-in context and releases the associated resources.
cp_status_t | cp_register_pcollection (cp_context_t *ctx, const char *dir)
| Registers a plug-in collection with a plug-in context.
void | cp_unregister_pcollection (cp_context_t *ctx, const char *dir)
| Unregisters a previously registered plug-in collection from a plug-in context.
void | cp_unregister_pcollections (cp_context_t *ctx)
| Unregisters all plug-in collections from a plug-in context.

## Function Documentation

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

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_status_t cp_register_pcollection | ( | cp_context_t * | ctx,
|  | const char * | dir |
| ) |  |  |

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

A 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.

Parameters:

  | ctx | the plug-in context
  | dir | the directory

Returns:
  CP_OK (zero) on success or CP_ERR_RESOURCE if insufficient memory

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.

Parameters:

  | ctx | the plug-in context
  | dir | the previously registered directory

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.

Parameters:

  | ctx | the plug-in context

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