x3py 作为一个轻量级的C++插件框架，面向C++开发人员，首要目标是能快速容易的开发出中小型的软件、软件以插件形式模块化设计。其插件既可灵活组合到各个系统，又能单独拆开使用和测试。
另外，x3py 可在Win/Linux/MacOSX等平台上编译运行，可使用VS或GCC编译，具备基本的跨平台兼容性。框架力求最简化，核心设计目标为“实用、简洁”。
我们客户端方面引入x3py主要是因为他即可以实现类似COM组件开发效果，又具有跨平台兼容性。这样我们可以很方便的实现一个跨平台的组件化客户端开发框架。在引入x3py后，我们实现的核心框架层次从下到上可以如下所示。
首先，x3manager也是一个插件，按照统一标准实现了插件的导出函数。x3manager插件的主要作用是在多个插件之间进行中介联系，从而允许插件之间能够互相访问而不直接发生联系，各个插件动态库加载后自动向x3manager登记。例如要创建一个对象，通过插件管理器来查询是在哪个插件中实现了该类，从而创建出对象、访问接口功能。
在x3py插件框架中，x3manager不负责插件动态库的加载管理，所以在C++的主程序或动态库中使用C++插件时，需要先加载各个插件动态库，然后就可使用插件接口。由于框架提供了多种加载方法，这样更灵活、职责更清晰。
使用 x3LoadLibrary 函数加载动态库文件。使用此函数而不是WinAPI的 LoadLibraryA 函数，是为了能实现跨平台同时确保自动调用 x3InitPlugin 函数进行插件初始化。
x3InitPlugin 函数用于在插件加载时进行初始化、向管理器注册（x3RegisterPlugin）此插件的所有类ID（CLSID串）。通过在插件CPP文件中包含 pluginimpl.h 文件，自动实现了 x3InitPlugin。插件动态库被多次加载时不会多次重复初始化，这是在 x3InitPlugin 函数中通过计数来保证的。
x3InitializePlugin 函数由各个插件自行实现，用来完成附加的初始化操作，由 x3InitPlugin 函数调用。
使用 x3FreeLibrary 函数卸载动态库文件。使用此函数而不是WinAPI的 FreeLibrary 函数，同样也是是为了能实现跨平台同时确保自动调用 x3FreePlugin 函数进行插件注销。
x3FreePlugin 函数用于在插件卸载时进行对象释放、向管理器注销（x3UnregisterPlugin）此插件的信息。通过在插件CPP文件中包含 pluginimpl.h 文件，自动实现了 x3FreePlugin。
x3UninitializePlugin 函数也是由各个插件自行实现，用来完成附加的资源释放操作，由 x3FreePlugin 函数调用。
通过使用智能指针模板类 x3::Object 来创建插件接口指针，自动处理引用计数。
x3::Object模板类通过x3::createObject函数去调用 x3manager中的x3CreateObject 来创建对象。如果插件自身的 x3InternalCreate 不能创建对象，则再转给x3manager，由后者根据类ID查找对应插件，然后调用对应插件的 x3InternalCreate 函数。
使用接口比较简单，在C++代码中包含相应的接口头文件，然后使用智能指针模板类 x3::Object 来创建对象或者从一个对象得到其他接口的对象。
下面的例子说明了如何创建对象、从一个对象得到其他接口的对象、使用接口函数：
#include <plsimple/isimple.h> // 包含接口文件
#include <plsimple/isimple2.h> // 包含其他接口文件
int test()
{
x3::Object<ISimple> obj(clsidSimple); // 给定类ID创建对象
if (obj) // 检查是否创建成功
{
obj->add(1, 2); // 调用接口函数，就像普通指针一样
}
x3::Object<ISimple2> other(obj.p()); // 从已有对象得到其他接口的实例吗，p()是获取obj的接口类指针
// other = obj.p(); // 除了拷贝构造，也可以使用赋值形式
if (other.valid())
{
std::vector<int> nums{1,2,3,4,5};
other->add(nums); // 调用新接口的函数
}
// 会自动释放对象
}
x3::AnyObject ，需要具体某个接口的对象时再转换。下面的例子就是插件的接口文件中 createSimple() 返回的是 x3::AnyObject，这样在此接口头文件中就可以不包含ISimple1的头文件：#ifndef X3_EXAMPLE_ISIMPLE3_H
#define X3_EXAMPLE_ISIMPLE3_H
#include <objptr.h>
const char* const clsidSimple3 = "94071767-ba6b-4769-9eb4-2ebf469218f3";
class ISimple3 : public x3::IObject
{
X3DEFINE_IID(ISimple3);
// 形参用AnyObject可避免包含其他接口定义文件，可在注释中说明实际接口名
virtual void useSimple(const x3::AnyObject& obj) = 0;
// 返回值用AnyObject可避免包含其他接口定义文件，可在注释中说明实际接口名
virtual x3::AnyObject createSimple() = 0;
// 而不是 virtual x3::Object<ISimple1> createSimple() = 0;
};
#endif
void CSimple::useSimple(const x3::AnyObject& obj)
{
x3::Object<ISimple> myobj(obj);
ASSERT(myobj);
x3::Object<ISimple> sample(createSimple());
ASSERT(sample);
}
x3::AnyObject CSimple::createSimple()
{
return x3::Object<ISimple>(clsidSimple);
// x3::Object<ISimple> simp(clsidSimple);
// do something with simp
// return simp;
}
#include <portability/x3port.h> // 相当于#include<windows.h>
#include <nonplugin/useplugins.h> // 包含辅助加载类，一个工程内只能包含一次
int main()
{
// 多个插件文件名，以NULL结尾
const char* plugins[] = {
"x3manager.pln", "plsimple.pln", "observerex.pln", NULL
};
// 自动加载和卸载插件，插件在程序文件的plugins子目录下
x3::AutoLoadPlugins autoload(plugins, "plugins");
// 可以使用接口了
return test();
}
#include <portability/x3port.h> // 相当于#include<windows.h>
// 插件在程序文件的plugins子目录下，如果不定义则插件与程序同目录
// 注意末尾有目录分隔符，在包含useplugin.h前定义，如果不定义则为默认的空串
#define PLUGIN_PATH "plugins/"
// 要使用的插件文件名，没有目录和后缀名(.pln)
#define PLUGIN_NAME "plsimple"
// 包含辅助加载类，一个工程内只能包含一次
#include <nonplugin/useplugin.h>
// 可以使用接口了
int main()
{
return test();
}
#include <nonplugin/scanplugins.h>
int main()
{
// 默认遍历 plugins 目录，加载其中的插件文件
x3::loadPlugins();
// 可以使用接口了
int ret = test();
// 卸载所有插件，后加载的先卸载
x3::unloadPlugins();
return ret;
}
#include <portability/portimpl.h>
HMODULE modules[10] = { NULL };
int main()
{
const char* plugins[] = {
"plugins/x3manager.pln",
"plugins/plsimple.pln",
"plugins/observerex.pln",
NULL
};
int count = 0;
for (int i = 0; plugins[i]; i++)
{
modules[count] = x3LoadLibrary(plugins[i]);
if (modules[count])
count++;
}
// 可以使用接口了
int ret = test();
while (--count >= 0)
{
x3FreeLibrary(modules[count]);
}
return ret;
}
namespace x3 {
class IObject;
bool createObject(const char* clsid, long iid, IObject** p)
{
typedef bool (*F)(const char*, long, IObject**);
F f = (F)GetProcAddress(modules[0], "x3CreateObject");
return f && f(clsid, iid, p);
}
} // x3
这种方式使用的比较少，就不具体介绍了，官方有一个具体的Wiki介绍，有兴趣的同学可以自己看看看。
#include <portability/x3port.h>
#include <module/pluginimpl.h>
#define XUSE_LIB_PLUGIN
#include <module/modulemacro.h>
XDEFINE_EMPTY_MODULE()
#ifdef _MSC_VER
#pragma comment(lib, "libpln1.lib")
#endif
extern const x3::ClassEntry* const classes_libpln1;
const x3::ClassEntry* const x3::ClassEntry::classes[] = {
s_classes, classes_libpln1, NULL
};
// 可以使用接口了
int main()
{
return test();
}
C++插件后缀名为 .pln ，而不是 .dll、.so、.plugin.dll ，其原因是在不同操作系统中用统一的后缀名，避免条件定义；同时避免与普通动态库混淆，这样遍历目录批量加载插件时可跳过普通动态库文件。
在VS中，我们可以通过工程属性–链接器–输出文件来设置编译出的插件dll后缀名为 .pln。
X3DEFINE_IID(接口名) 定义接口ID。X3DEFINE_IID 和 x3::IObject 定义在 iobject.h 中，但通常我们包含 objptr.h 更方便些，下面是一个接口头文件isimple.h：#ifndef X3_EXAMPLE_ISIMPLE_H
#define X3_EXAMPLE_ISIMPLE_H
#include <objptr.h>
class ISimple : public x3::IObject
{
X3DEFINE_IID(ISimple);
virtual int add(int a, int b) const = 0;
virtual int subtract(int a, int b) const = 0;
};
#endif
const char* const clsidSimple = "94071767-ba6b-4769-9eb4-2ebf469289f3";
注意：类UID不可重复，否则将会覆盖已向管理器注册的类，导致其他模块无法创建原来类的接口对象。
X3BEGIN_CLASS_DECLARE 等宏来指定一个类实现了哪些接口。这里的CSimple是一个实现类的例子。其中构造函数和析构函数申明为保护函数，所有实现的接口函数申明为私有函数，这是推荐方式，但不是必须的。这样做是为了明确表明不允许直接实例化和delete销毁，也不允许直接调用实现类的接口函数。#ifndef X3_EXAMPLE_SIMPLE_IMPL_H
#define X3_EXAMPLE_SIMPLE_IMPL_H
#include <plsimple/isimple.h> // 包含接口定义
class CSimple : public ISimple // 从接口派生
{
X3BEGIN_CLASS_DECLARE(CSimple, clsidSimple) // 指定类ID
X3DEFINE_INTERFACE_ENTRY(ISimple) // 指定实现的接口
X3END_CLASS_DECLARE()
protected:
CSimple();
virtual ~CSimple();
private:
virtual int add(int a, int b) const;
virtual int subtract(int a, int b) const;
};
#endif
#ifndef X3_EXAMPLE_SIMPLE_IMPL2_H
#define X3_EXAMPLE_SIMPLE_IMPL2_H
#include "plsimple.h" // 包含基实现类
#include <plsimple/isimple2.h> // 包含附加接口
#include <plsimple/isimple3.h>
class CSimple2
: public CSimple // 从基实现类派生
, public ISimple2 // 从附加接口派生
, public ISimple3
{
X3BEGIN_CLASS_DECLARE(CSimple2, clsidSimple)
X3DEFINE_INTERFACE_ENTRY(ISimple2) // 指定实现的接口
X3DEFINE_INTERFACE_ENTRY(ISimple3)
X3USE_INTERFACE_ENTRY(CSimple) // 继承已实现的所有接口
X3END_CLASS_DECLARE()
protected:
CSimple2() {}
private:
virtual int add(const std::vector<int>& nums) const;
virtual x3::AnyObject createSimple();
};
#endif
因为插件中的实现类一般不直接用于实例化对象，而是通过 x3::Object 智能指针模板类来创建对象的。所以，我们需要在插件中注册可供实例化的类以及说明此类是否是单例。
注册实现类的通常做法是在工程的一个.cpp文件（通常为 module.cpp）中，包含 pluginimpl.h 和 modulemacro.h 文件，然后使用 XBEGIN_DEFINE_MODULE 等宏来申明注册哪些实现类。下面是示例：
#include <module/plugininc.h>
#include <module/pluginimpl.h> // 实现插件的导出函数
#include <module/modulemacro.h> // 注册实现类的宏定义
#include "plsimple.h" // 包含实现类
XBEGIN_DEFINE_MODULE()
XDEFINE_CLASSMAP_ENTRY(CSimple) // 注册普通实现类或单实例类
XDEFINE_CLASSMAP_ENTRY_Singleton(YourSingletonClass)
XEND_DEFINE_MODULE_DLL() // 插件动态库
OUTAPI bool x3InitializePlugin() // 插件加载时执行，用于额外初始化
{
return true;
}
OUTAPI void x3UninitializePlugin() // 插件卸载时执行，用于释放额外数据
{
}
其中 x3InitializePlugin() 和 x3UninitializePlugin() 函数由自己实现，用于额外的初始化和释放操作。这两个函数可以在module.cpp或其他.cpp文件中实现，但是在同一个插件中只能实现一次。
如果某个插件不实现任何接口，只使用其他插件的接口，则可以在module.cpp中使用下面更简单的形式：
#include <module/pluginimpl.h>
#include <module/modulemacro.h>
XDEFINE_EMPTY_MODULE()
.cpp文件中一般都会包含stdafx.h，因此 module/plugininc.h 文件无论包含与否都可。使用VS时可以不需要 module/plugininc.h 和 interface\core\portability 目录。x3py官方也提供了事件驱动机制，其的主要用途是在不同模块之间实现松耦合（相互隔离）、将复杂的调用流程分离为多个独立操作片断、实现功能扩展点。但其实现比较简单，只支持最多两个参数。所以，我们可以引入信号槽或者其他方法来替换。