4.3.1.7 Plugin Meta-Information

It is possible and common to use SCF interfaces and objects directly via the C++ class names, via creation functions, or via facilities which return pointers to pure SCF interfaces. However, when an external plugin modules publishes a class implementing an SCF interface, the client of that plugin can not access the object directly via C++. This is where the SCF class name comes into play. An SCF class name is an abitrary string assigned to the implementation. The string is passed to scfCreateInstance() in order to create an instance of the named object. If necessary, SCF will load the plugin which implements the named object in order to satisfy the request. The SCF class name can be anything you like, though it is often useful to impose a hierarchical interpretation on the name. For instance, `crystalspace.graphics3d.opengl'.

The data which describes a plugin module, such as the SCF class names and C++ implementations which the plugin exports, is known as meta-information. Each plugin has an associated meta-information resource which describes the plugin module. This information can be accessed without even loading the plugin module. At development time, the meta-information is maintained in an XML-format text file which has the same name as the plugin module, but with extension `.csplugin'. Here is a sample meta-information resource for a plugin named `myplugin' (`myplugin.so' on Unix, `myplugin.dll' on Windows):

<?xml version="1.0"?>
<!-- myplugin.csplugin -->
<plugin>
  <scf>
    <classes>
      <class>
        <name>myproj.myplugin.foo1</name>
        <implementation>MyClass1</implementation>
        <description>My first custom foo class</description>
      </class>
      <class>
        <name>myproj.myplugin.foo2</name>
        <implementation>MyClass2</implementation>
        <description>My second custom foo class</description>
        <requires>
          <class>myproj.myplugin.bar1</class>
          <class>myproj.myplugin.bar2</class>
        </requires>
      </class>
    </classes>
  </scf>
</plugin>

The top-level node of a meta-information file is named <plugin>. All SCF-related information is contained within an <scf> child node. Plugin modules can export multiple named SCF classes. Each exported class is represented by a <class> node within the <classes> group. The <name> node of a <class> is the class' SCF name. The <implementation> node references the C++ class which actually implements the named SCF class. This is the same name that is privided as an argument to the SCF_IMPLEMENT_FACTORY() macro. When an SCF class depends upon other SCF classes, the dependencies are indicated via the optional <requires> group, which contains one <class> node per dependency.

The above example meta-information resource indicates that the plugin exports two C++ classes, `MyClass1' and `MyClass2' under the SCF class names `myproj.myplugin.foo1' and `myproj.myplugin.foo2', respectively. Furthermore, the second exported class has a dependency upon two other SCF classes, `myproj.myplugin.bar1' and `myproj.myplugin.bar2'. SCF will ensure that these other classes are loaded before it instantiates `MyClass2'.

Meta-information in the `.csplugin' file is extensible; it is not restricted to SCF-only usage. Plugin authors can choose to publish supplementary information about plugins in addition to the SCF information already published. As a hypothetical example, image loading plugins might desire to publish image indentification information which would allow the image loading multiplexor to selectively request image loading plugins on-demand, rather than requesting all plugins unconditionally, even if they are not needed. Here is a possible meta-information table for a PNG image loader (with the <scf> node collapsed to `...' for the sake of illustration):

<?xml version="1.0"?>
<!-- cspngimg.csplugin -->
<plugin>
  <scf>...</scf>
  <imageloader>
    <imagetype>
      <class>crystalspace.graphic.image.io.png</class>
      <identify>
        <mimetype>image/png</mimetype>
        <extension>png</extension>
        <extension>PNG</extension>
        <scan length="4" bytes="\0x89PNG"/>
     </identify>
    </imagetype>
  </imageloader>
</plugin>

In this example, the PNG loader meta-information tells the multiplexor several different ways to identify a PNG image:

• By checking MIME type, if available.
• By checking file extension, if available.
• By checking for the magic identification string `\0x89PNG' in the raw image data.

If the multiplexor identifies the image as PNG, only then will it actually request the PNG loader plugin.

This document was generated using texi2html 1.76.