Qt5该插件机制（4）--QtMeta信息窗口小部件metaData

<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

JSON 与Qt插件的元信息 MetaData

Qt插件的源代码中。基本都能见到一个 xxx.json 的文件，这个文件里通常仅仅包括一句：

{
    "Keys": [ "yyy" ]
}

我们能够猜到这个文件里的"Keys"应该是指定了与插件相关的keyword。那这个 .json 文件究竟是怎样起作用的?
先来认识一下 JSON .

JSON是一种存储结构化数据的格式，它有6中基本数据类型。各自是：

bool    布尔型。取值能够是 true 或 false
double    数字类型
string    字符串类型
array    数组类型
object    对象类型
null    空类型

详细可參见 Qt Assistant 中关于"JSON Support in Qt "的介绍。

A simple JSON document encoding a person, his/her age, address and phone numbers could look like:

{
    "FirstName": "John",    # FirstName是变量(字段)的名称；John是变量的值
    "LastName": "Doe",
    "Age": 43,
    "Address": {
        "Street": "Downing Street 10",
        "City": "London",
        "Country": "Great Britain"
    },
    "Phone numbers": [
        "+44 1234567",
        "+44 2345678"
    ]
}

值得一提的是，数组类型的字段在.json文件里赋值时应该用方括号 '[' 和 ']' 括起来，对象类型的字段在赋值时
应用花括号 '{' 和 '}' 括起来，普通类型的数据则不须要括。每个 .json 文件描写叙述了一个 JSON对象，而一个JSON
对象中的对象类型字段，又能够看做是一个子JSON对象（JSON对象的嵌套）。
再回过头来看看插件源代码中的 xxx.json 文件，能够发现当中的变量 Keys 事实上是个数组变量（由于它赋值时用方括号
括住了），仅仅只是这个数组中通常仅仅有一个元素而已。即一个插件一般仅仅有一个keyword，当然也能够为一个插件设置多个
keyword。

.json在Qt插件中主要用于存储Qt插件的元信息(metaData)。在Qt中，有一个专门的类 QJsonObject 来描写叙述一个JSON。
QLibraryPrivate::metaData() 返回的是一个QJsonObject类的指针，通过这个指针能够訪问该 QLibraryPrivate 对象相应的库的元信息；
QFactoryLoader::metaData() 返回的是一个 QList<QJsonObject> 列表，这个列表中顺序存放了与该 QFactoryLoader 对象相关的全部库
的元信息（动态库的元信息在前，静态库的元信息在后）。

另外值得注意的是，QLibraryPrivate::metaData() 返回的QJsonObject对象中一般都有一个 MetaData 字段，这个字段是对象类型的数据。
他能够看做是库的元信息的一个子JSON对象，并且它相应的就是 .json 文件里的内容。

（.json文件里的内容仅仅是一个库的元信息的一部分）

每一个QFactoryLoader对象都有一个 d->iid 成员 (d是与QFactoryLoader对象关联的QFactoryLoaderPrivate实例)。可用于描写叙述插件的种类，
每一类插件都有一个独立的 IID 值， 比方平台输入法类插件的IDD都应该是 org.qt-project.Qt.QPlatformInputContextFactoryInterface，
平台类插件的IDD都应是 org.qt-project.Qt.QPA.QPlatformIntegrationFactoryInterface.5.2 等。



<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

QLibraryPrivate的metaData（库的元信息）的产生过程

在编写Qt插件时须要用到 Q_PLUGIN_METADATA 这个宏来设置一个插件的元信息，但在Qt的源代码中。发现这个宏是空的。所以不用说。这个
宏是被MOC解析的而不是C++编译器。

那就看看MOC会怎么对付这个宏吧。找了个非常easy的文件。用moc处理一下，看看都生成了什么。

main.cpp文件内容例如以下。当中使用了Q_PLUGIN_METADATA宏

#include <qpa/qplatforminputcontextplugin_p.h>
#include <QtCore/QStringList>
#include "QtMinimalInputMethodFrame.h"
QT_BEGIN_NAMESPACE
class QtMinimalInputMethodFramePlugin : public QPlatformInputContextPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QPlatformInputContextFactoryInterface" FILE "qtminimal.json")    // 指定了IID和.json文件

public:
    QtMinimalInputMethodFrame *create(const QString &, const QStringList &);
};
QtMinimalInputMethodFrame *QtMinimalInputMethodFramePlugin::create(const QString &system, const QStringList ¶mList)
{
    Q_UNUSED(paramList);
    if (system.compare(system, QStringLiteral("qtminimal"), Qt::CaseInsensitive) == 0)
        return new QtMinimalInputMethodFrame;
    return 0;
}
QT_END_NAMESPACE
#include "main.moc"

qtminimal.json文件内容例如以下：

{
    "Keys": [ "qtminimal" ]
}

使用 "moc main.cpp moc_main.cpp" ，生成moc_main.cpp文件，打开。发现里面有一部分代码例如以下：

    ...
    ...

static const unsigned char qt_pluginMetaData[] = {
    'Q', 'T', 'M', 'E', 'T', 'A', 'D', 'A', 'T', 'A', ' ', ' ',        // "QTMETADATA",这段字符串可看做Qt的插件元信息的头，通过这个keyword能搜索到元信息的位置
    0x71, 0x62, 0x6a, 0x73, 0x01, 0x00, 0x00, 0x00,
    0x00, 0x01, 0x00, 0x00, 0x0b, 0x00, 0x00, 0x00,
    0xec, 0x00, 0x00, 0x00, 0x1b, 0x03, 0x00, 0x00,
    0x03, 0x00, 0x49, 0x49, 0x44, 0x00, 0x00, 0x00,
    0x37, 0x00, 0x6f, 0x72, 0x67, 0x2e, 0x71, 0x74,
    0x2d, 0x70, 0x72, 0x6f, 0x6a, 0x65, 0x63, 0x74,
    0x2e, 0x51, 0x74, 0x2e, 0x51, 0x50, 0x6c, 0x61,
    0x74, 0x66, 0x6f, 0x72, 0x6d, 0x49, 0x6e, 0x70,
    0x75, 0x74, 0x43, 0x6f, 0x6e, 0x74, 0x65, 0x78,
    0x74, 0x46, 0x61, 0x63, 0x74, 0x6f, 0x72, 0x79,
    0x49, 0x6e, 0x74, 0x65, 0x72, 0x66, 0x61, 0x63,
    0x65, 0x00, 0x00, 0x00, 0x9b, 0x0c, 0x00, 0x00,
    0x09, 0x00, 0x63, 0x6c, 0x61, 0x73, 0x73, 0x4e,
    0x61, 0x6d, 0x65, 0x00, 0x1f, 0x00, 0x51, 0x74,
    0x4d, 0x69, 0x6e, 0x69, 0x6d, 0x61, 0x6c, 0x49,
    0x6e, 0x70, 0x75, 0x74, 0x4d, 0x65, 0x74, 0x68,
    0x6f, 0x64, 0x46, 0x72, 0x61, 0x6d, 0x65, 0x50,
    0x6c, 0x75, 0x67, 0x69, 0x6e, 0x00, 0x00, 0x00,
    0x5a, 0x60, 0xa0, 0x00, 0x07, 0x00, 0x76, 0x65,
    0x72, 0x73, 0x69, 0x6f, 0x6e, 0x00, 0x00, 0x00,
    0x11, 0x00, 0x00, 0x00, 0x05, 0x00, 0x64, 0x65,
    0x62, 0x75, 0x67, 0x00, 0x95, 0x16, 0x00, 0x00,
    0x08, 0x00, 0x4d, 0x65, 0x74, 0x61, 0x44, 0x61,
    0x74, 0x61, 0x00, 0x00, 0x38, 0x00, 0x00, 0x00,
    0x03, 0x00, 0x00, 0x00, 0x34, 0x00, 0x00, 0x00,
    0x14, 0x03, 0x00, 0x00, 0x04, 0x00, 0x4b, 0x65,
    0x79, 0x73, 0x00, 0x00, 0x1c, 0x00, 0x00, 0x00,
    0x02, 0x00, 0x00, 0x00, 0x18, 0x00, 0x00, 0x00,
    0x09, 0x00, 0x71, 0x74, 0x6d, 0x69, 0x6e, 0x69,
    0x6d, 0x61, 0x6c, 0x00, 0x8b, 0x01, 0x00, 0x00,
    0x0c, 0x00, 0x00, 0x00, 0x0c, 0x00, 0x00, 0x00,
    0xa4, 0x00, 0x00, 0x00, 0x54, 0x00, 0x00, 0x00,
    0x98, 0x00, 0x00, 0x00, 0x88, 0x00, 0x00, 0x00
};
    ...
    ...

// 留意一下QT_MOC_EXPORT_PLUGIN这个宏
QT_MOC_EXPORT_PLUGIN(QtMinimalInputMethodFramePlugin, QtMinimalInputMethodFramePlugin)    

    ...
    ...

上面的代码中生成了一个名为 qt_pluginMetaData 的数组。看其名字就能猜出来这个数组是与插件的元信息有关的，
将该数组用字符显示，结果为：

QTMETADATA  qbjs^A^@^@^@^@^A^@^@^K^@^@^@ì^@^@^@^[^C^@^@^C^@
IID^@^@^@7^@org.qt-project.Qt.QPlatformInputContextFactoryInterface    // IDD
^@^@^@<9b>^L^@^@^@        
className^@^_^@QtMinimalInputMethodFramePlugin        // 类名
^@^@^@Z` ^@^G^@
version^@^@^@^Q^@^@^@^E^@            // 版本号
debug^@<95>^V^@^@^H^@                // debug
MetaData^@^@8^@^@^@^C^@^@^@4^@^@^@^T^C^@^@^D^@    // MetaData
Keys^@^@^^@^@^@^B^@^@^@^X^@^@^@^@qtminimal    // Keys
^@<8b>^A^@^@^L^@^@^@^L^@^@^@¤^@^@^@T^@^@^@<98>^@^@^@<88>^@^@^@

能够看到当中已经包括了IDD、Keys等信息，因此能够确定与插件相关的元信息就是存在这个数组中。
上面给出的代码最后。使用了QT_MOC_EXPORT_PLUGIN宏，它的作用是定义两个函数。qt_plugin_instance() 和
qt_plugin_query_metadata(),前者用于返回插件类（QtMinimalInputMethodFramePlugin）的一个实例，后者用于
返回数组qt_pluginMetaData的指针。

因此。当这个库被载入后。通过库中的qt_plugin_query_metadata()函数就能够获得
库的元信息数组（二进制数据）。

#define Q_PLUGIN_INSTANCE(IMPLEMENTATION)     // 这个宏用于返回一个类名是IMPLEMENTATION的类的静态实例
        { 
            static QT_PREPEND_NAMESPACE(QPointer)<QT_PREPEND_NAMESPACE(QObject)> _instance; 
            if (!_instance)      
                _instance = new IMPLEMENTATION; 
            return _instance; 
        }

#if defined(QT_STATICPLUGIN)
    // 这部分是静态编译时用的宏。我们暂无论它
#  define QT_MOC_EXPORT_PLUGIN(PLUGINCLASS, PLUGINCLASSNAME) 
    static QT_PREPEND_NAMESPACE(QObject) *qt_plugin_instance_##PLUGINCLASSNAME() 
    Q_PLUGIN_INSTANCE(PLUGINCLASS) 
    static const char *qt_plugin_query_metadata_##PLUGINCLASSNAME() { return (const char *)qt_pluginMetaData; } 
    const QT_PREPEND_NAMESPACE(QStaticPlugin) qt_static_plugin_##PLUGINCLASSNAME() { 
        QT_PREPEND_NAMESPACE(QStaticPlugin) plugin = { qt_plugin_instance_##PLUGINCLASSNAME, qt_plugin_query_metadata_##PLUGINCLASSNAME}; 
        return plugin; 
    }

#else
    // 这部分才是动态编译时用的宏
#  define QT_MOC_EXPORT_PLUGIN(PLUGINCLASS, PLUGINCLASSNAME)      
            Q_EXTERN_C Q_DECL_EXPORT 
            const char *qt_plugin_query_metadata()             // 这个函数返回一个指针，指向元信息数组
            { return (const char *)qt_pluginMetaData; } 
            Q_EXTERN_C Q_DECL_EXPORT QT_PREPEND_NAMESPACE(QObject) *qt_plugin_instance()  这个函数返回插件类PLUGINCLASS的一个静态实例
            Q_PLUGIN_INSTANCE(PLUGINCLASS)

#endif

我们尽管能够通过qt_plugin_query_metadata()函数获得库的元信息数组（二进制数据），可是还须要把这些
二进制数据转换成 QJsonObject 对象。这样才方便在程序中对其各个字段进行訪问。

QLibraryPrivate类有个
静态成员函数fromRawMetaData。能够从二进制数据中构造一个 QJsonDocument 对象，
而QJsonDocument对象的 object() 方法就能返回所需的 QJsonObject 对象（库的元信息）。
通过这些能够推測，QLibraryPrivate类的 metaData 成员是这样被设置的：
载入一个库文件后，将库中的qt_plugin_query_metadata()这个符号resolve出来。并通过它得到数组 qt_pluginMetaData 的指针，
然后调用QLibraryPrivate类的fromRawMetaData方法讲二进制存储的元信息转换到一个QJsonObject 对象中，最后将这个对象赋值
给QLibraryPrivate类的metaData成员。


如今问题是。 QLibraryPrivate的metaData是在哪里，被谁设置的？

当第一次使用 QLibraryPrivate类的 isPlugin() 方法调查一个库是否是插件时。这种方法内部会调用 QLibraryPrivate::updatePluginState() 。

bool QLibraryPrivate::isPlugin()
{
    if (pluginState == MightBeAPlugin)    // pluginState在构造函数中会被初始化为MightBeAPlugin
        updatePluginState();

    return pluginState == IsAPlugin;
}

而QLibraryPrivate::updatePluginState()函数中。须要读取QLibraryPrivate类的 metaData 信息来确认一个库是不是插件。而 metaData 也就是在这时
被设置的。从这个函数中还能够看出，仅仅有Qt插件才有 metaData 元信息。 普通的库是没有的（这一点我上不能打保票。只是从以下这个函数的代码上看，应该
是这种）。

void QLibraryPrivate::updatePluginState()
{
    errorString.clear();
    if (pluginState != MightBeAPlugin)
        return;        // 假设pluginState的状态已经确定了，则直接返回

    bool success = false;

#if defined(Q_OS_UNIX) && !defined(Q_OS_MAC)
    if (fileName.endsWith(QLatin1String(".debug"))) {
        // refuse to load a file that ends in .debug
        // these are the debug symbols from the libraries
        // the problem is that they are valid shared library files
        // and dlopen is known to crash while opening them

        // pretend we didn't see the file
        errorString = QLibrary::tr("The shared library was not found.");
        pluginState = IsNotAPlugin;
        return;
    }
#endif

    // 这里開始设置 metaData 。findPatternUnloaded() 和 qt_get_metadata() 两个函数的内部都会设置 metaData
    if (!pHnd) {
    // 假设库还没有被载入。(pHnd==NULL说明库未被载入）。则调用findPatternUnloaded函数。它内部会
    // 讲相应的库文件打开，读取其内容。在当中寻找Qt的插件元信息的头Header（就是前面提到的"QTMETADATA"）。
    // 假设找到了。就解析元信息。这样的方法的优点是在不载入库的情况下也能获得其元信息。
        // scan for the plugin metadata without loading
        success = findPatternUnloaded(fileName, this);    
    } else {
    // 假设库已被载入，则调用qt_get_metadata获得元信息。
    // QtPluginQueryVerificationDataFunction是一个函数指针类型。其详细类型是 :  char*(*)(), 它返回
    // 一个字符指针（指向一个二进制数组），准确的说，他应该返回上面提到的qt_pluginMetaData数组的指针 。

        // library is already loaded (probably via QLibrary)
        // simply get the target function and call it.
        QtPluginQueryVerificationDataFunction getMetaData = NULL;
        getMetaData = (QtPluginQueryVerificationDataFunction) resolve("qt_plugin_query_metadata");    
        // 上面这行将库中的qt_plugin_query_metadata符号resolve出来
        success = qt_get_metadata(getMetaData, this);
    }

    if (!success) {
    // 假设获取 元信息 失败。即当前库没有元信息，就将pluginState设置为IsNotAPlugin。代表非Qt插件。
    // 这里由于当前库没有元信息，就觉得它不是Qt插件。所以这是不是意味着。仅仅有Qt插件才有元信息而普通库是没有的?
        if (errorString.isEmpty()){
            if (fileName.isEmpty())
                errorString = QLibrary::tr("The shared library was not found.");
            else
                errorString = QLibrary::tr("The file '%1' is not a valid Qt plugin.").arg(fileName);
        }
        pluginState = IsNotAPlugin;
        return;
    }

    pluginState = IsNotAPlugin; // be pessimistic

    // 假设获取 元信息 成功，再看版本是否符合要求。假设版本合适，则将pluginState设置为IsAPlugin。代表是Qt插件
    uint qt_version = (uint)metaData.value(QLatin1String("version")).toDouble();
    bool debug = metaData.value(QLatin1String("debug")).toBool();
    if ((qt_version & 0x00ff00) > (QT_VERSION & 0x00ff00) || (qt_version & 0xff0000) != (QT_VERSION & 0xff0000)) {
        if (qt_debug_component()) {
            qWarning("In %s:
"
                 "  Plugin uses incompatible Qt library (%d.%d.%d) [%s]",
                 (const char*) QFile::encodeName(fileName),
                 (qt_version&0xff0000) >> 16, (qt_version&0xff00) >> 8, qt_version&0xff,
                 debug ? "debug" : "release");
        }
        errorString = QLibrary::tr("The plugin '%1' uses incompatible Qt library. (%2.%3.%4) [%5]")
            .arg(fileName)
            .arg((qt_version&0xff0000) >> 16)
            .arg((qt_version&0xff00) >> 8)
            .arg(qt_version&0xff)
            .arg(debug ? QLatin1String("debug") : QLatin1String("release"));
#ifndef QT_NO_DEBUG_PLUGIN_CHECK
    } else if(debug != QLIBRARY_AS_DEBUG) {
        //don't issue a qWarning since we will hopefully find a non-debug?
 --Sam
        errorString = QLibrary::tr("The plugin '%1' uses incompatible Qt library."
                 " (Cannot mix debug and release libraries.)").arg(fileName);
#endif
    } else {
        pluginState = IsAPlugin;
    }
}

版权声明：本文博客原创文章。博客，未经同意，不得转载。