C-Pluff C API  0.2.0


Plug-in is the core element of an extensible application. The extensions and also the main application logic are implemented as plug-ins. Plug-ins can be developed, distributed and deployed independently, subject to inter-plugin dependencies. Deploying a new plug-in does not require recompilation or relinking if the operating system platform supports required dynamic linking facilities.


A plug-in includes the following structural elements.

Plug-in descriptor

A plug-in descriptor is an XML document describing a plug-in. It includes information about the contents of the plug-in, the features provided by the plug-in, plug-in version information and static dependencies of the plug-in. Most of the elements are optional. Most of the descriptor information described here is available to software via cp_plugin_info_t structure. The plug-in descriptor must be located in the plug-in directory as plugin.xml.

The formal declaration of plug-in descriptor is available as XML Schema Definition in plugin.xsd located in the top level source directory. Currently there is no namespace associated with the plug-in descriptor. Here is an example of a plug-in descriptor. Click element name to jump into documentation for that element.

<plugin id="org.c-pluff.example" name="Example Plug-in" version="0.3.2" provider-name="Johannes Lehtinen">
    <backwards-compatibility abi="0.3" api="0.2.8"/>
        <c-pluff version="0.1"/>
        <import plugin="org.c-pluff.util" version="0.2"/>
        <import plugin="org.c-pluff.extra" optional="true"/> 
    <runtime library="libruntime" funcs="org_cpluff_example_funcs"/>
    <extension-point id="editors" name="Text Editors" schema="editors_schema.xsd"/>
    <extension-point id="url-families"/>
    <extension point="org.c-pluff.util.archivers" id="tar" name="Tar Archiver Support">
        <type random-access="false"/>
        <exec bin="tar"/>
    <extension point="org.c-pluff.example.editors</span>&gt;
        &lt;editor name=<span class="charliteral">"Text Editor"</span> runtime=<span class="charliteral">"org_cpluff_example_txteditor_runtime">
                <file-type mime-type="text/plain"/>

A descriptor can also be much simpler, depending on the plug-in. Here is an example of a minimal descriptor (of a useless plug-in).

<plugin id="org.c-pluff.useless"/>


This is the top level element of the plug-in descriptor. It can have following attributes.

This element can contain following elements.


This element includes optional information about the backwards compatibility of this plug-in version. It can have following attributes.

These apply to plug-ins that provide header files and runtime libraries. For example, a plug-in might export global functions to other plug-ins or it might provide an extension point where an extension installed by other plug-in must conform to data structures defined by the plug-in. Both attributes are optional.


This element includes information about static plug-in dependencies. It can be omitted if there are no dependencies. It can contain following elements.


This element declares a version dependency on the C-Pluff implementation. It can be used to ensure that the plug-in is not loaded by incompatible C-Pluff version. It has the following attribute.


This element declares a static dependency on other plug-in. It must be used when a plug-in uses global symbols or data from other plug-in or when a plug-in uses an extension point defined by other plug-in or whenever some other plug-in needs to be there for the plug-in to work. The framework takes care of resolving and starting the dependencies whenever the plug-in is resolved or started.

This element can have following attributes.


This element contains information about the plug-in runtime library. It is omitted if the plug-in does not have a runtime library but contains only data. It can have following attributes.


This element defines an extension point provided by the plug-in. It can have following attributes.


This element defines an extension installed into a specified extension point provided by the defining plug-in or some other plug-in. It can have following attributes.

The extension element can contain XML elements specific to the associated extension point (conforming to the schema defined by the extension point).

Plug-in runtime library

A plug-in runtime library is an optional plug-in element. Plug-ins only supplying static data in form of XML data and files do not need a runtime library. However, a typical plug-in does provide program logic as well.

The plug-in runtime library includes all program logic and program data provided by the plug-in. It is simply a shared library, or a dynamically linked library, which is linked in to the application when the plug-in is started. When plug-in is unloaded, the runtime library is unloaded as well. The framework has been designed to manage dependencies so that unloading of the runtime library does not cause problems, provided that plug-ins behave properly.

A plug-in can expose functionality to other plug-ins either as exported global symbols that are directly resolved by other plug-ins or by supplying extensions. When other plug-ins are directly using exported symbols the plug-in acts just like any standard shared library. Nothing special there. The more interesting case is exposing functionality as extensions. Because the extension is registered at a specific extension point, the logic in other plug-ins can use the extension and the associated program logic even if they are not aware of the existence of the extension supplying plug-in.

The extension points accepting program logic as extensions define a way to specify the name of the symbol pointing to the supplied logic. This is typically an attribute of an XML element contained in the extension definition. The plug-in supplying the extension can then export the program logic as a global symbol with arbitrary name and then place the name of the symbol in extension data. Alternatively, the plug-in can define a virtual symbol at runtime using cp_define_symbol. Other plug-ins that are using extensions registered at the extension point can then resolve the named symbol using cp_resolve_symbol at runtime. The framework automatically creates a dependency from the symbol using plug-in to the symbol supplying plug-in to prevent failures in case the symbol supplying plug-in is stopped or unloaded.

Static plug-in data

Plug-in can supply static data to other plug-ins using at least two different mechanisms. A plug-in can easily provide static XML data as part of extension elements. Additionally, a plug-in directory can contain files that may be accessed by other plug-ins. Currently the platform does not provide assistance in accessing data files provided by other plug-ins. However, a plug-in can locate the plug-in directory and thus any included data files by using plug-in path available in cp_plugin_info_t structure of the data providing plug-in.

Generated on Fri May 1 2020 01:06:58 for C-Pluff C API by doxygen 1.8.13