service/protocol-plugin/lib/cpluff/doc/reference/c-api/plugin.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
   3 <title>C-Pluff C API: Plug-in</title>
   4 <link href="doxygen.css" rel="stylesheet" type="text/css">
   5 <link href="tabs.css" rel="stylesheet" type="text/css">
   6 </head><body>
   7 <!-- Generated by Doxygen 1.5.1 -->
   8 <div class="tabs">
   9   <ul>
  10     <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
  11     <li><a href="modules.html"><span>Modules</span></a></li>
  12     <li><a href="annotated.html"><span>Data&nbsp;Structures</span></a></li>
  13     <li><a href="files.html"><span>Files</span></a></li>
  14     <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
  15   </ul></div>
  16 <h1><a class="anchor" name="plugin">Plug-in</a></h1><h2><a class="anchor" name="pluginOverview">
  17 Overview</a></h2>
  18 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.<h2><a class="anchor" name="pluginStructure">
  19 Structure</a></h2>
  20 A plug-in includes the following structural elements.<p>
  21 <ul>
  22 <li><a class="el" href="plugin.html#pluginDescriptor">Plug-in descriptor</a></li><li><a class="el" href="plugin.html#pluginRuntime">Plug-in runtime library</a></li><li><a class="el" href="plugin.html#pluginData">Static plug-in data</a></li></ul>
  23 <h3><a class="anchor" name="pluginDescriptor">
  24 Plug-in descriptor</a></h3>
  25 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 <a class="el" href="structcp__plugin__info__t.html">cp_plugin_info_t</a> structure. The plug-in descriptor must be located in the plug-in directory as <code>plugin.xml</code>.<p>
  26 The formal declaration of plug-in descriptor is available as XML Schema Definition in <code>plugin.xsd</code> 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.<p>
  27 <div class="fragment"> <pre class="fragment">
  28  &lt;<a href="#pluginDescPlugin" class="code">plugin</a> id=<span class="charliteral">"org.c-pluff.example"</span> name=<span class="charliteral">"Example Plug-in"</span> version=<span class="charliteral">"0.3.2"</span> provider-name=<span class="charliteral">"Johannes Lehtinen"</span>&gt;
  29      &lt;<a href="#pluginDescPluginBWC" class="code">backwards-compatibility</a> abi=<span class="charliteral">"0.3"</span> api=<span class="charliteral">"0.2.8"</span>/&gt;
  30      &lt;<a href="#pluginDescPluginRequires" class="code">requires</a>&gt;
  31          &lt;<a href="#pluginDescPluginReqCP" class="code">c-pluff</a> version=<span class="charliteral">"0.1"</span>/&gt;
  32          &lt;<a href="#pluginDescPluginReqImport" class="code">import</a> plugin=<span class="charliteral">"org.c-pluff.util"</span> version=<span class="charliteral">"0.2"</span>/&gt;
  33          &lt;<a href="#pluginDescPluginReqImport" class="code">import</a> plugin=<span class="charliteral">"org.c-pluff.extra"</span> optional=<span class="charliteral">"true"</span>/&gt;
  34      &lt;/<a href="#pluginDescPluginRequires" class="code">requires</a>&gt;
  35      &lt;<a href="#pluginDescPluginRuntime" class="code">runtime</a> library=<span class="charliteral">"libruntime"</span> funcs=<span class="charliteral">"org_cpluff_example_funcs"</span>/&gt;
  36      &lt;<a href="#pluginDescPluginEP" class="code">extension-point</a> id=<span class="charliteral">"editors"</span> name=<span class="charliteral">"Text Editors"</span> schema=<span class="charliteral">"editors_schema.xsd"</span>/&gt;
  37      &lt;<a href="#pluginDescPluginEP" class="code">extension-point</a> id=<span class="charliteral">"url-families"</span>/&gt;
  38      &lt;<a href="#pluginDescPluginE" class="code">extension</a> point=<span class="charliteral">"org.c-pluff.util.archivers"</span> id=<span class="charliteral">"tar"</span> name=<span class="charliteral">"Tar Archiver Support"</span>&gt;
  39          &lt;type random-access=<span class="charliteral">"false"</span>/&gt;
  40          &lt;exec bin=<span class="charliteral">"tar"</span>/&gt;
  41      &lt;/<a href="#pluginDescPluginE" class="code">extension</a>&gt;
  42      &lt;<a href="#pluginDescPluginE" class="code">extension</a> point=<span class="charliteral">"org.c-pluff.example.editors</span>&gt;
  43          &lt;editor name=<span class="charliteral">"Text Editor"</span> runtime=<span class="charliteral">"org_cpluff_example_txteditor_runtime"</span>&gt;
  44              &lt;file-types&gt;
  45                  &lt;file-type mime-type=<span class="charliteral">"text/plain"</span>/&gt;
  46              &lt;/file-types&gt;
  47          &lt;/editor&gt;
  48      &lt;/<a href="#pluginDescPluginE" class="code">extension</a>&gt;
  49  &lt;/<a href="#pluginDescPlugin" class="code">plugin</a>&gt;</pre> </div><p>
  50 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).<p>
  51 <div class="fragment"> <pre class="fragment">
  52  &lt;<a href="#pluginDescPlugin" class="code">plugin</a> id=<span class="charliteral">"org.c-pluff.useless"</span>/&gt;</pre> </div><h4><a class="anchor" name="pluginDescPlugin">
  53 plugin</a></h4>
  54 This is the top level element of the plug-in descriptor. It can have following attributes.<p>
  55 <ul>
  56 <li><em>id:</em> A mandatory unique identifier for the plug-in. Plug-in identifiers should preferably be generated using a reversed DNS domain name as prefix to prevent identifier conflicts.</li><li><em>name:</em> An optional human-readable name for the plug-in.</li><li><em>version:</em> An optional version number for the plug-in. Version numbers are used for checking compatibility when resolving versioned plug-in dependencies. See also information about plug-in versions.</li><li><em>provider-name</em>: The name of the plug-in provider or author. Optional.</li></ul>
  57 <p>
  58 This element can contain following elements.<p>
  59 <ul>
  60 <li><a class="el" href="plugin.html#pluginDescPluginBWC">backwards-compatibility</a>: Optional information about backwards compatibility of this plug-in version.</li><li><a class="el" href="plugin.html#pluginDescPluginRequires">requires</a>: Information about static plug-in dependencies. Can be omitted if the plug-in does not have static dependencies.</li><li><a class="el" href="plugin.html#pluginDescPluginRuntime">runtime</a>: Information about the plug-in runtime library. Can be omitted if the plug-in does not have a runtime library but only data.</li><li><a class="el" href="plugin.html#pluginDescPluginEP">extension-point</a>: Information about extension points provided by the plug-in. This element is repeated if there are multiple extension points and omitted if there are none.</li><li><a class="el" href="plugin.html#pluginDescPluginE">extension</a>: Information about extensions provided by the plug-in. This element is repeated if there are multiple extensions and omitted if there are none.</li></ul>
  61 <h4><a class="anchor" name="pluginDescPluginBWC">
  62 backwards-compatibility</a></h4>
  63 This element includes optional information about the backwards compatibility of this plug-in version. It can have following attributes.<p>
  64 <ul>
  65 <li><em>abi:</em> Backwards compatibility of the application binary interface (ABI) of the plug-in. ABI includes any public symbols exported by the plug-in, data structures associated with exported symbols and any extension points provided by the plug-in. The ABI of the current plug-in version is backwards compatible with any plug-in version from the version specified here to the current version. This information is used when resolving versioned plug-in dependencies. See also information about plug-in versions.</li><li><em>api:</em> Backwards compatibility of the application programming interface (API) of the plug-in. API compatibility means that source code developed against one version of the plug-in also compiles against another version of the plug-in. This information is not used by framework but it can be used by a developer developing dependent plug-ins.</li></ul>
  66 <p>
  67 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.<h4><a class="anchor" name="pluginDescPluginRequires">
  68 requires</a></h4>
  69 This element includes information about static plug-in dependencies. It can be omitted if there are no dependencies. It can contain following elements.<p>
  70 <ul>
  71 <li><a class="el" href="plugin.html#pluginDescPluginReqCP">c-pluff</a>: An optional version dependency on the C-Pluff implementation.</li><li><a class="el" href="plugin.html#pluginDescPluginReqImport">import</a>: Declares a static dependency on other plug-in. This element is repeated if there are multiple dependencies and omitted if there are none.</li></ul>
  72 <h4><a class="anchor" name="pluginDescPluginReqCP">
  73 c-pluff</a></h4>
  74 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.<p>
  75 <ul>
  76 <li><em>version:</em> The required version of the C-Pluff implementation. This is used when resolving the plug-in. It is checked that the used C-Pluff implementation is backwards compatible with the version specified here when it comes to the application binary interface (ABI) of C-Pluff.</li></ul>
  77 <h4><a class="anchor" name="pluginDescPluginReqImport">
  78 import</a></h4>
  79 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.<p>
  80 This element can have following attributes.<p>
  81 <ul>
  82 <li><em>plugin:</em> The identifier of the imported plug-in.</li><li><em>version:</em> An optional version dependency on the imported plug-in. The plug-in can be resolved only if the version of the imported plug-in is backwards compatible with the version specified here when it comes to the application binary interface (ABI) of the imported plug-in.</li><li><em>optional:</em> Is the import optional or not ("true" or "false"). Default is false, a mandatory import. An optional import behaves just like the mandatory import as long as the imported plug-in is present. However, if it is not present then the import is ignored. Optional import can be used if the plug-in works in limited capacity even without the specified plug-in.</li></ul>
  83 <h4><a class="anchor" name="pluginDescPluginRuntime">
  84 runtime</a></h4>
  85 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.<p>
  86 <ul>
  87 <li><em>library:</em> The name of the plug-in runtime library in the plug-in directory. A platform specific extension (for example, ".so" or ".dll") is added to the value specified here when loading the library.</li><li><em>funcs:</em> The functions to be used to create an instance of the plug-in runtime. This attribute is optional. It is needed if the plug-in has a start or stop function. The value specified here is a name of an exported symbol which contains a pointer to <a class="el" href="structcp__plugin__runtime__t.html">cp_plugin_runtime_t</a> structure.</li></ul>
  88 <h4><a class="anchor" name="pluginDescPluginEP">
  89 extension-point</a></h4>
  90 This element defines an extension point provided by the plug-in. It can have following attributes.<p>
  91 <ul>
  92 <li><em>id:</em> The local identifier of the extension point. The value specified here is prefixed with the identifier of the plug-in and dot to construct the global identifier of the extension point.</li><li><em>name:</em> An optional human-readable name describing the use of the extension point.</li><li><em>schema:</em> An optional path to the extension point XML schema in the plug-in directory. This information is not currently used by the framework. But it can be used by a developer to determine what information should be provided by extensions attached to this extension point.</li></ul>
  93 <h4><a class="anchor" name="pluginDescPluginE">
  94 extension</a></h4>
  95 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.<p>
  96 <ul>
  97 <li><em>point:</em> The global identifier of the associated extension point.</li><li><em>id:</em> An optional local identifier for the extension. The value specified here is prefixed with the identifier of the plug-in and dot to construct the global identifier for the extension.</li><li><em>name:</em> An optional human-readable name describing the extension.</li></ul>
  98 <p>
  99 The extension element can contain XML elements specific to the associated extension point (conforming to the schema defined by the extension point).<h3><a class="anchor" name="pluginRuntime">
 100 Plug-in runtime library</a></h3>
 101 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.<p>
 102 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.<p>
 103 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.<p>
 104 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 <a class="el" href="group__cFuncsSymbols.html#g9d128b52c0ffe2d4215026fe59f9abeb">cp_define_symbol</a>. Other plug-ins that are using extensions registered at the extension point can then resolve the named symbol using <a class="el" href="group__cFuncsSymbols.html#g8bc3b7fcf4f4ed414837f5a3998d46b7">cp_resolve_symbol</a> 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.<h3><a class="anchor" name="pluginData">
 105 Static plug-in data</a></h3>
 106 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 <a class="el" href="structcp__plugin__info__t.html">cp_plugin_info_t</a> structure of the data providing plug-in. <hr size="1">
 107 <p class="footer">
 108 <a href="http://www.c-pluff.org/">C-Pluff</a>, a plug-in framework for C<br>
 109 Copyright 2007 <a href="http://www.jlehtinen.net/">Johannes Lehtinen</a>
 110 </p>
 111 <p class="generated-by">
 112 Generated on Fri Apr 6 15:40:55 2007 for C-Pluff C API by&nbsp;<a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.1
 113 </p>
 114 </body>
 115 </html>