Класс PIPluginLoader

Загрузчик плагина. Подробнее...

#include <piplugin.h>

Открытые типы
enum	Error { Unknown , NoError , NoSuchFile , InvalidUserVersion }
	Возможные ошибки загрузки плагина Подробнее...
typedef int(*)	FunctionLoaderVersion()
	Сигнатура экспортируемой функции версии загрузчика.
typedef void(*)	FunctionStaticMerge(int, void *, void *)
	Сигнатура экспортируемой функции слияния статических секций.

Открытые члены
	PIPluginLoader (const PIString &name=PIString())
	Создает загрузчик с базовым именем файла "name" и вызывает load() если "name" не пустое
	~PIPluginLoader ()
	Деструктор, выгружает библиотеку
bool	load (const PIString &name)
	Загружает плагин по базовому имени файла name и обновляет состояние ошибки при неудаче.
void	unload ()
	Выгружает плагин и освобождает библиотеку
bool	isLoaded () const
	Возвращает успешно ли загружен плагин
Error	lastError () const
	Возвращает ошибку последнего вызова load().
PIString	lastErrorText () const
	Возвращает сообщение об ошибке последнего вызова load().
void	setMessages (bool yes)
	Устанавливает должен ли PIPluginLoader выводить сообщения, true по умолчанию
bool	isMessages () const
	Возвращает должен ли PIPluginLoader выводить сообщения, true по умолчанию
PIString	libPath ()
	Возвращает путь к загруженной библиотеке
void *	resolve (const char *name)
	Получает экспортированный метод библиотеки с именем "symbol".
void	mergeStatic ()
	Вызывает у плагина PIP_PLUGIN_STATIC_SECTION_MERGE.

Открытые статические члены
static PIStringList	pluginsDirectories (const PIString &name)
	Возвращает существующие каталоги плагинов для подкаталога name.

Относящиеся к классу:
(не члены класса)
#define	PIP_PLUGIN
	Объявляет точки входа плагина и должен использоваться перед другими макросами PIP_PLUGIN_*.
#define	PIP_PLUGIN_SET_USER_VERSION(version)
	Устанавливает строковую пользовательскую версию, проверяемую при загрузке, "version" - строка в кавычках.
#define	PIP_PLUGIN_ADD_STATIC_SECTION(type, ptr)
	Регистрирует указатель на статическую секцию для последующего слияния. type - целочисленный ключ.
#define	PIP_PLUGIN_STATIC_SECTION_MERGE
	Объявляет функцию для слияния статических секций плагина и приложения.
#define	PIP_PLUGIN_EXPORT
	Помечает функцию плагина для экспорта.

Подробное описание

Загрузчик плагина.

Управляет загрузкой динамических библиотек, разрешением символов и жизненным циклом плагинов

Краткий обзор

Этот файл предоставляет несколько макросов для объявления плагина и PIPluginLoader - класс для его загрузки и проверки.

Сторона плагина

Плагин - это разделяемая библиотека, которая может быть загружена динамически. Необходимым является только макрос PIP_PLUGIN. Можно установить версию для дополнительной проверки с помощью макроса PIP_PLUGIN_SET_USER_VERSION(version). Также можно объявить метод для слияния статических секций между приложением и плагином с помощью макроса PIP_PLUGIN_STATIC_SECTION_MERGE. Перед слиянием необходимо установить указатели для секций с помощью макроса PIP_PLUGIN_ADD_STATIC_SECTION(type, ptr).

Сторона приложения

Приложение должно использовать класс PIPluginLoader для загрузки плагина. Основной метод - это load(PIString name). "name" является базовым именем для поиска библиотеки. PIPluginLoader попробует несколько имен, <name>, lib<name> и расширения "dll", "so" и "dylib", в зависимости от системы.
Например:

PIPluginLoader l;
l.load("foo");

На Windows будут опробованы "foo", "libfoo", "foo.dll" и "libfoo.dll".
Если нужна проверка пользовательской версии, установите ей с помощью макроса PIP_PLUGIN_SET_USER_VERSION(version). Когда плагин будет успешно загружен и проверен, можно будет получать из него свои методы с помощью resolve(name), аналогично PILibrary.

Заметки

Необходимо использовать PIP_PLUGIN_EXPORT и C-linkage для методов, получаемых через resolve(name)!

Статические секции

Макрос PIP_PLUGIN_STATIC_SECTION_MERGE объявляет метод с аргументами (int type, void * from, void * to), поэтому можно оставить его как объявление, или реализовать тут же:

PIP_PLUGIN_STATIC_SECTION_MERGE() {
    switch (type) {
    ...
    }
}

Заметки

При использовании синглтонов надо помнить, что реализованные в cpp синглтоны в разделяемых библиотеках едины для всего приложения, включая плагины! Однако реализованные в h-файлах синглтоны, либо из статических библиотек, не являются реальными одиночками, и для каждого плагина и приложения будет свой объект. В этом случае можно провести слияние статических секций.

В любом случае, если используется макрос PIP_PLUGIN_STATIC_SECTION_MERGE, то он вызывается первый раз во время загрузки плагина с "from" - областью плагина, "to" - областью приложения, и второй раз (необязательно) при вызове mergeStatic() с "from" - областью приложения и "to" - областью плагина.
Первый вызов позволяет скопировать статические секции из плагина в приложение, второй - из приложения (и всех остальных плагинов) в плагин.

Примеры

Простой плагин:

#include <piplugin.h>
 
PIP_PLUGIN
 
extern "C" {
    PIP_PLUGIN_EXPORT void myFunc() {
        piCout << "Hello plugin!";
    }
}

Приложение:

#include <piplugin.h>
int main() {
    PIPluginLoader pl;
    pl.load("your_lib");
    if (pl.isLoaded()) {
        typedef void(*MyFunc)();
        MyFunc f = (MyFunc)pl.resolve("myFunc");
        if (f) f();
    }
    return 0;
}

Сложный плагин:

#include <piplugin.h>
 
PIStringList global_list;
 
PIP_PLUGIN
PIP_PLUGIN_SET_USER_VERSION("1.0.0")
PIP_PLUGIN_ADD_STATIC_SECTION(1, &global_list)
 
STATIC_INITIALIZER_BEGIN
    global_list << "plugin_init";
STATIC_INITIALIZER_END
 
PIP_PLUGIN_STATIC_SECTION_MERGE {
    PIStringList * sfrom = (PIStringList*)from, * sto = (PIStringList*)to;
    *sto << *sfrom;
    sto->removeDuplicates();
}

Приложение:

#include <piplugin.h>
 
PIStringList global_list;
 
PIP_PLUGIN_SET_USER_VERSION("1.0.0");
PIP_PLUGIN_ADD_STATIC_SECTION(1, &global_list);
 
int main() {
    global_list << "app";
    PIPluginLoader pl;
    pl.load("your_lib");
    pl.mergeStatic();
    piCout << "list =" << global_list;
    return 0;
}

Перечисления

Error

enum PIPluginLoader::Error

Возможные ошибки загрузки плагина

Элементы перечислений
Unknown	Не было вызова load()
NoError	Нет ошибки
NoSuchFile	Не найден файл библиотеки */, LibraryLoadError /** \~english System cant load library Система не смогла загрузить библиотеку */, MissingSymbols /** Нет необходимых методов */, InvalidLoaderVersion /** Неверная внутренняя версия
InvalidUserVersion	Неверная пользовательская версия

Методы

load()

bool PIPluginLoader::load

(

const PIString &

name

)

Загружает плагин по базовому имени файла name и обновляет состояние ошибки при неудаче.

Загрузчик пробует приставку "lib" и окончания ".dll", ".so" или ".dylib", в зависимости от системы

resolve()

void * PIPluginLoader::resolve

(

const char *

name

)

Получает экспортированный метод библиотеки с именем "symbol".

См. также

PILibrary::resolve()

mergeStatic()

void PIPluginLoader::mergeStatic

(

)

Вызывает у плагина PIP_PLUGIN_STATIC_SECTION_MERGE.

Вызывает функцию слияния статических секций плагина для синхронизации данных приложения и плагина

Друзья класса и относящимся к классу обозначения

PIP_PLUGIN_STATIC_SECTION_MERGE

#define PIP_PLUGIN_STATIC_SECTION_MERGE

related

Объявляет функцию для слияния статических секций плагина и приложения.

Этот метод имеет 3 аргумента: (int type, void * from, void * to). Он вызывается первый раз при загрузке плагина с "from" - областью плагина, "to" - областью приложения, и второй раз (необязательно) при вызове PIPluginLoader::mergeStatic() с "from" - областью приложения и "to" - областью плагина. Таким образом, этот макрос позволяет провести слияние статических данных приложения и плагина.