Skip to content

Plug-in Side

We’ll start by creating the Eagle and Jaguar classes. Then we write a connection function to add the respective providers to the host.

Implementing a shared interface

Let’s start with the Eagle. It inherits from Warrior, so first of all include it.

#include "Warrior.hpp"

Don’t forget to tell the compiler about the location of the Warrior header so that it can find it.
The Eagle class is just another common C++ class.

class Eagle: public Warrior{
public:
    std::string getDescription(){
        return "Eagle Warrior: soldier of the sun";
    }
};

The plug-in will add a provider of Eagle warriors to the host, so we need to declare an EagleProvider class, which is a WarriorProvider itself. Pluma does it for us with a macro:

PLUMA_INHERIT_PROVIDER(Type, BaseType)

Where Type inherits from BaseType, and a class BaseTypeProvider exists (ie, BaseType is a shared interface). In our example, after the Eagle declaration we put:

PLUMA_INHERIT_PROVIDER(Eagle, Warrior);

To use this macro we need to include the Pluma main header:

#include <Pluma/Pluma.hpp>

At this point we have a classe Eagle and a class EagleProvider.
Proceed the same way for the Jaguar class.

Connection function

A plug-in connects to a host application through a connection function. In Windows the connect function is “special” (a C export function), we’ll use an elegant macro for it. The connector macro is defined at the Connector.hpp header.

#include <Pluma/Connector.hpp>

PLUMA_CONNECTOR
bool connect(pluma::Host& host){
    ...
}

That macro isn’t really needed for other systems, but it’s better to use it for better portability (you may want to port your application for Windows later). Note: don’t put a semicolon after this macro, it is part of the connect function signature.

The host argument has this useful function:

bool Host::add(Provider* provider);

The provider pointer passed will be managed by the host, including it’s deletion, so never delete a provider after passing it through an add function call.
Let’s add some providers:

host.add( new EagleProvider() );
host.add( new JaguarProvider() );

Finally we return true to tell that everything went fine.
Don’t forget to include the Eagle and Jaguar headers.
Build your plugin.

Testing compatibility and canceling a connection (advanced)

What are those bool returns you may ask? The add function return false if the type of the provider that you’re trying to add isn’t accepted by that host, or if plug-in and host are using incompatible versions of the shared interface. Usually a plugin don’t have to worry about that, but you may want for example to test the result of the add function to add something else that you have on the plug-in. Note: even when add return false, the provider pointer passed is always deleted.

Finally, if you return false on the connect function, it will tell the host to cancel everything that you may have added. On the following example, all successful added providers are canceled if the provider an fails.

host.add(a1);
host.add(a2);
...
if (!host.add(an))
     return false;

Conclusion

So, a plug-in consists in one or more implementations of shared interfaces, and a connect function to give the host the providers of your classes. On the next page we’ll use our plug-in in a host application.


Index || Shared Interface << A Plug-in Application >>  Host Side