--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/corelib/plugin/qpluginloader.cpp Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,434 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "qplatformdefs.h"
+
+#include "qplugin.h"
+#include "qpluginloader.h"
+#include <qfileinfo.h>
+#include "qlibrary_p.h"
+#include "qdebug.h"
+#include "qdir.h"
+
+#if defined(Q_OS_SYMBIAN)
+# include <f32file.h>
+# include "private/qcore_symbian_p.h"
+#endif
+
+#ifndef QT_NO_LIBRARY
+
+QT_BEGIN_NAMESPACE
+
+/*!
+ \class QPluginLoader
+ \reentrant
+ \brief The QPluginLoader class loads a plugin at run-time.
+
+
+ \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();
+ // If not found directly, check also all the available drives
+ if (!fn.length()) {
+ QString stubPath(fi.fileName().length() ? fi.absoluteFilePath() : QString());
+ if (stubPath.length() > 1) {
+ if (stubPath.at(1).toAscii() == ':')
+ stubPath.remove(0,2);
+ QFileInfoList driveList(QDir::drives());
+ RFs rfs = qt_s60GetRFs();
+ foreach(const QFileInfo& drive, driveList) {
+ QString testFilePath(drive.absolutePath() + stubPath);
+ testFilePath = QDir::cleanPath(testFilePath);
+ // Use native Symbian code to check for file existence, because checking
+ // for file from under non-existent protected dir like E:/private/<uid> using
+ // QFile::exists causes platform security violations on most apps.
+ QString nativePath = QDir::toNativeSeparators(testFilePath);
+ TPtrC ptr(qt_QString2TPtrC(nativePath));
+ TUint attributes;
+ TInt err = rfs.Att(ptr, attributes);
+ if (err == KErrNone) {
+ fn = testFilePath;
+ break;
+ }
+ }
+ }
+ }
+
+#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