diff options
Diffstat (limited to 'src/corelib/plugin/qpluginloader.cpp')
| -rw-r--r-- | src/corelib/plugin/qpluginloader.cpp | 402 |
1 files changed, 402 insertions, 0 deletions
diff --git a/src/corelib/plugin/qpluginloader.cpp b/src/corelib/plugin/qpluginloader.cpp new file mode 100644 index 0000000..a911f1d --- /dev/null +++ b/src/corelib/plugin/qpluginloader.cpp @@ -0,0 +1,402 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the QtCore module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "qplatformdefs.h" + +#include "qplugin.h" +#include "qpluginloader.h" +#include <qfileinfo.h> +#include "qlibrary_p.h" +#include "qdebug.h" + +#ifndef QT_NO_LIBRARY + +QT_BEGIN_NAMESPACE + +/*! + \class QPluginLoader + \reentrant + \brief The QPluginLoader class loads a plugin at run-time. + + \mainclass + \ingroup plugins + + QPluginLoader provides access to a \l{How to Create Qt + Plugins}{Qt plugin}. A Qt plugin is stored in a shared library (a + DLL) and offers these benefits over shared libraries accessed + using QLibrary: + + \list + \o QPluginLoader checks that a plugin is linked against the same + version of Qt as the application. + \o QPluginLoader provides direct access to a root component object + (instance()), instead of forcing you to resolve a C function manually. + \endlist + + An instance of a QPluginLoader object operates on a single shared + library file, which we call a plugin. It provides access to the + functionality in the plugin in a platform-independent way. To + specify which plugin to load, either pass a file name in + the constructor or set it with setFileName(). + + The most important functions are load() to dynamically load the + plugin file, isLoaded() to check whether loading was successful, + and instance() to access the root component in the plugin. The + instance() function implicitly tries to load the plugin if it has + not been loaded yet. Multiple instances of QPluginLoader can be + used to access the same physical plugin. + + Once loaded, plugins remain in memory until all instances of + QPluginLoader has been unloaded, or until the application + terminates. You can attempt to unload a plugin using unload(), + but if other instances of QPluginLoader are using the same + library, the call will fail, and unloading will only happen when + every instance has called unload(). Right before the unloading + happen, the root component will also be deleted. + + In order to speed up loading and validation of plugins, some of + the information that is collected during loading is cached in + persistent memory (through QSettings). For instance, the result + of a load operation (e.g. succeeded or failed) is stored in the + cache, so that subsequent load operations don't try to load an + invalid plugin. However, if the "last modified" timestamp of + a plugin has changed, the plugin's cache entry is invalidated + and the plugin is reloaded regardless of the values in the cache + entry. The cache entry is then updated with the new result of the + load operation. + + This also means that the timestamp must be updated each time the + plugin or any dependent resources (such as a shared library) is + updated, since the dependent resources might influence the result + of loading a plugin. + + See \l{How to Create Qt Plugins} for more information about + how to make your application extensible through plugins. + + Note that the QPluginLoader cannot be used if your application is + statically linked against Qt. In this case, you will also have to + link to plugins statically. You can use QLibrary if you need to + load dynamic libraries in a statically linked application. + + \note In Symbian the plugin stub files must be used whenever a + path to plugin is needed. For the purposes of loading plugins, + the stubs can be considered to have the same name as the actual + plugin binary. In practice they have ".qtplugin" extension + instead of ".dll", but this difference is handled transparently + by QPluginLoader and QLibrary to avoid need for Symbian specific + plugin handling in most Qt applications. Plugin stubs are needed + because Symbian Platform Security denies all access to the directory + where the actual plugin binaries are located. + + \sa QLibrary, {Plug & Paint Example} +*/ + +/*! + Constructs a plugin loader with the given \a parent. +*/ +QPluginLoader::QPluginLoader(QObject *parent) + : QObject(parent), d(0), did_load(false) +{ +} + +/*! + Constructs a plugin loader with the given \a parent that will + load the plugin specified by \a fileName. + + To be loadable, the file's suffix must be a valid suffix for a + loadable library in accordance with the platform, e.g. \c .so on + Unix, - \c .dylib on Mac OS X, and \c .dll on Windows. The suffix + can be verified with QLibrary::isLibrary(). + + Note: In Symbian the \a fileName must point to plugin stub file. + + \sa setFileName() +*/ +QPluginLoader::QPluginLoader(const QString &fileName, QObject *parent) + : QObject(parent), d(0), did_load(false) +{ + setFileName(fileName); +} + +/*! + Destroys the QPluginLoader object. + + Unless unload() was called explicitly, the plugin stays in memory + until the application terminates. + + \sa isLoaded(), unload() +*/ +QPluginLoader::~QPluginLoader() +{ + if (d) + d->release(); +} + +/*! + Returns the root component object of the plugin. The plugin is + loaded if necessary. The function returns 0 if the plugin could + not be loaded or if the root component object could not be + instantiated. + + If the root component object was destroyed, calling this function + creates a new instance. + + The root component, returned by this function, is not deleted when + the QPluginLoader is destroyed. If you want to ensure that the root + component is deleted, you should call unload() as soon you don't + need to access the core component anymore. When the library is + finally unloaded, the root component will automatically be deleted. + + The component object is a QObject. Use qobject_cast() to access + interfaces you are interested in. + + \sa load() +*/ +QObject *QPluginLoader::instance() +{ + if (!load()) + return 0; + if (d->instance) + return d->instance(); + return 0; +} + +/*! + Loads the plugin and returns true if the plugin was loaded + successfully; otherwise returns false. Since instance() always + calls this function before resolving any symbols it is not + necessary to call it explicitly. In some situations you might want + the plugin loaded in advance, in which case you would use this + function. + + \sa unload() +*/ +bool QPluginLoader::load() +{ + if (!d || d->fileName.isEmpty()) + return false; + if (did_load) + return d->pHnd && d->instance; + if (!d->isPlugin()) + return false; + did_load = true; + return d->loadPlugin(); +} + + +/*! + Unloads the plugin and returns true if the plugin could be + unloaded; otherwise returns false. + + This happens automatically on application termination, so you + shouldn't normally need to call this function. + + If other instances of QPluginLoader are using the same plugin, the + call will fail, and unloading will only happen when every instance + has called unload(). + + Don't try to delete the root component. Instead rely on + that unload() will automatically delete it when needed. + + \sa instance(), load() +*/ +bool QPluginLoader::unload() +{ + if (did_load) { + did_load = false; + return d->unload(); + } + if (d) // Ouch + d->errorString = tr("The plugin was not loaded."); + return false; +} + +/*! + Returns true if the plugin is loaded; otherwise returns false. + + \sa load() + */ +bool QPluginLoader::isLoaded() const +{ + return d && d->pHnd && d->instance; +} + +/*! + \property QPluginLoader::fileName + \brief the file name of the plugin + + To be loadable, the file's suffix must be a valid suffix for a + loadable library in accordance with the platform, e.g. \c .so on + Unix, \c .dylib on Mac OS X, and \c .dll on Windows. The suffix + can be verified with QLibrary::isLibrary(). + + If the file name does not exist, it will not be set. This property + will then contain an empty string. + + By default, this property contains an empty string. + + Note: In Symbian the \a fileName must point to plugin stub file. + + \sa load() +*/ +void QPluginLoader::setFileName(const QString &fileName) +{ +#if defined(QT_SHARED) + QLibrary::LoadHints lh; + if (d) { + lh = d->loadHints; + d->release(); + d = 0; + did_load = false; + } + +#if defined(Q_OS_SYMBIAN) + // In Symbian we actually look for plugin stub, so modify the filename + // to make canonicalFilePath find the file, if .dll is specified. + QFileInfo fi(fileName); + + if (fi.suffix() == QLatin1String("dll")) { + QString stubName = fileName; + stubName.chop(3); + stubName += QLatin1String("qtplugin"); + fi = QFileInfo(stubName); + } + + QString fn = fi.canonicalFilePath(); +#else + QString fn = QFileInfo(fileName).canonicalFilePath(); +#endif + + d = QLibraryPrivate::findOrCreate(fn); + d->loadHints = lh; + if (fn.isEmpty()) + d->errorString = QLibrary::tr("The shared library was not found."); +#else + if (qt_debug_component()) { + qWarning("Cannot load %s into a statically linked Qt library.", + (const char*)QFile::encodeName(fileName)); + } + Q_UNUSED(fileName); +#endif +} + +QString QPluginLoader::fileName() const +{ + if (d) + return d->fileName; + return QString(); +} + +/*! + \since 4.2 + + Returns a text string with the description of the last error that occurred. +*/ +QString QPluginLoader::errorString() const +{ + return (!d || d->errorString.isEmpty()) ? tr("Unknown error") : d->errorString; +} + +typedef QList<QtPluginInstanceFunction> StaticInstanceFunctionList; +Q_GLOBAL_STATIC(StaticInstanceFunctionList, staticInstanceFunctionList) + +/*! \since 4.4 + + \property QPluginLoader::loadHints + \brief Give the load() function some hints on how it should behave. + + You can give hints on how the symbols in the plugin are + resolved. By default, none of the hints are set. + + See the documentation of QLibrary::loadHints for a complete + description of how this property works. + + \sa QLibrary::loadHints +*/ + +void QPluginLoader::setLoadHints(QLibrary::LoadHints loadHints) +{ + if (!d) { + d = QLibraryPrivate::findOrCreate(QString()); // ugly, but we need a d-ptr + d->errorString.clear(); + } + d->loadHints = loadHints; +} + +QLibrary::LoadHints QPluginLoader::loadHints() const +{ + if (!d) { + QPluginLoader *that = const_cast<QPluginLoader *>(this); + that->d = QLibraryPrivate::findOrCreate(QString()); // ugly, but we need a d-ptr + that->d->errorString.clear(); + } + return d->loadHints; +} + +/*! + \relates QPluginLoader + \since 4.4 + + Registers the given \a function with the plugin loader. +*/ +void Q_CORE_EXPORT qRegisterStaticPluginInstanceFunction(QtPluginInstanceFunction function) +{ + staticInstanceFunctionList()->append(function); +} + +/*! + Returns a list of static plugin instances (root components) held + by the plugin loader. +*/ +QObjectList QPluginLoader::staticInstances() +{ + QObjectList instances; + StaticInstanceFunctionList *functions = staticInstanceFunctionList(); + if (functions) { + for (int i = 0; i < functions->count(); ++i) + instances.append((*functions)[i]()); + } + return instances; +} + +QT_END_NAMESPACE + +#endif // QT_NO_LIBRARY |