Plugins

Plugins

1. Description
2. HowTo File Plugin

Description

Kuriimu2 utilizes DLLs as plugins to extend its file format support.

Those DLLs are written in C# and loaded at runtime using MEF (Microsoft Extensibility Framework). MEF reduces the code required to load dlls at runtime, making it much easier to load them. Additionally it allows loading metadata for a plugin, instead of initializing it, which makes it faster to get metadata and more memory efficient. To make use of MEFs capabilities in code, one must first reference the System.CompositionModel assembly.

HowTo File Plugin

The first type of plugin is the widely used file-based one. It's a plugin that loads a given file and interprets it into a more general and/or readable structure for either the UI or other programs.

Coding a basic file plugin for Kuriimu2 is just combining different interfaces depending on its needs.

The general implementation order for plugin interfaces goes as follows:

• Type (top level): ITextAdapter, IImageAdapter, IArchiveAdapter, etc...
• File Capability: IIdentifyFiles, ICreateFiles, ILoadFiles, ISaveFiles
• Type Functionality: IAddEntries, IImportImages, IAddFiles, etc...

This is for style, readability and consistency between plugins.

You should normally only implement a single top level interface per plugin definition. This helps keep the plugins purpose specific without bloating Identify() and Load() with tons of type checking when two separate plugins would be much cleaner.

You should include interfaces which your plugin can properly support. An example of incorrect usage would be to implement IIdentifyFiles but then have the Identify() function do a poor job where it returns false-positives very often for files that the plugin doesn't actually deal with.

OPF: Maybe the next two paragraphs can simply be a link to the full interface details page?

Optionally one can inherit from ISaveFiles to enable save capability and IIdentifyFiles to enable pre-load identification of a file.

If a file is not identifiable (since it doesn't inherit from IIdentifyFiles), this plugin will be marked as blind. It will later be listed in the event arguments of IdentificationFailed.

To make use of Kuriimu2's UI you need to implement one of the top level interfaces. This also requires that you export the interface type via the MEF Export attribute from the System.CompositionModel assembly. Plugins that don't export the interface will be ignored by Kore since all plugins are loaded via MEF imports.

Information about PluginInfo and PluginExtensionInfo can be found here.

Example:

using System.CompositionModel;

[Export(typeof(IIdentifyFiles))] // Export IIdentifyFiles so Kore allows auto-selection of this plugin.
[Export(typeof(ILoadFiles))]     // Export ILoadFiles so Kore allows this plugin to receive loaded files.
// Without exporting IImageAdapter, Kore won't know that this plugin is actually an image plugin
// and thus the Kuriimu2 UI won't load the plugin at all.
[PluginInfo("GUID", "Name", "ShortName", "Author", "Website", "Description")]
[PluginExtensionInfo("*.ext")]   // Defines the extension(s) that this plugin looks for by default.
public class Plugin : IImageAdapter, IIdentifyFiles, ILoadFiles
{
    public IList<BitmapInfo> BitmapInfos { get; }

    public bool Identify(string filename)
    {
        // Here the file gets read, to identify it and to check if this plugin can handle it.
        // Not inheriting from IIdentifyFiles makes Kore treat this plugin as a [[Blind Plugin]].
    }

    public void Load(string filename)
    {
        // Here the file gets read and loaded to provide the necessay data to the output of the interface.
        // In this case Load should populate the BitmapInfos list.
    }

    public void Dispose()
    {
        // Every interface from Kontract inherits from IDisposable and therefore each plugin instance is disposable.
    }
}