1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtCore module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qplatformdefs.h"

    43 

    44 #include "qplugin.h"

    45 #include "qpluginloader.h"

    46 #include <qfileinfo.h>

    47 #include "qlibrary_p.h"

    48 #include "qdebug.h"

    49 #include "qdir.h"

    50 

    51 #if defined(Q_OS_SYMBIAN)

    52 # include <f32file.h>

    53 # include "private/qcore_symbian_p.h"

    54 #endif

    55 

    56 #ifndef QT_NO_LIBRARY

    57 

    58 QT_BEGIN_NAMESPACE

    59 

    60 /*!

    61     \class QPluginLoader

    62     \reentrant

    63     \brief The QPluginLoader class loads a plugin at run-time.

    64 

    65 

    66     \ingroup plugins

    67 

    68     QPluginLoader provides access to a \l{How to Create Qt

    69     Plugins}{Qt plugin}. A Qt plugin is stored in a shared library (a

    70     DLL) and offers these benefits over shared libraries accessed

    71     using QLibrary:

    72 

    73     \list

    74     \o QPluginLoader checks that a plugin is linked against the same

    75        version of Qt as the application.

    76     \o QPluginLoader provides direct access to a root component object

    77        (instance()), instead of forcing you to resolve a C function manually.

    78     \endlist

    79 

    80     An instance of a QPluginLoader object operates on a single shared

    81     library file, which we call a plugin. It provides access to the

    82     functionality in the plugin in a platform-independent way. To

    83     specify which plugin to load, either pass a file name in

    84     the constructor or set it with setFileName().

    85 

    86     The most important functions are load() to dynamically load the

    87     plugin file, isLoaded() to check whether loading was successful,

    88     and instance() to access the root component in the plugin. The

    89     instance() function implicitly tries to load the plugin if it has

    90     not been loaded yet. Multiple instances of QPluginLoader can be

    91     used to access the same physical plugin.

    92 

    93     Once loaded, plugins remain in memory until all instances of

    94     QPluginLoader has been unloaded, or until the application

    95     terminates. You can attempt to unload a plugin using unload(),

    96     but if other instances of QPluginLoader are using the same

    97     library, the call will fail, and unloading will only happen when

    98     every instance has called unload(). Right before the unloading

    99     happen, the root component will also be deleted.

   100 

   101     In order to speed up loading and validation of plugins, some of

   102     the information that is collected during loading is cached in

   103     persistent memory (through QSettings). For instance, the result

   104     of a load operation (e.g. succeeded or failed) is stored in the

   105     cache, so that subsequent load operations don't try to load an

   106     invalid plugin. However, if the "last modified" timestamp of

   107     a plugin has changed, the plugin's cache entry is invalidated

   108     and the plugin is reloaded regardless of the values in the cache

   109     entry. The cache entry is then updated with the new result of the

   110     load operation.

   111 

   112     This also means that the timestamp must be updated each time the

   113     plugin or any dependent resources (such as a shared library) is

   114     updated, since the dependent resources might influence the result

   115     of loading a plugin.

   116 

   117     See \l{How to Create Qt Plugins} for more information about

   118     how to make your application extensible through plugins.

   119 

   120     Note that the QPluginLoader cannot be used if your application is

   121     statically linked against Qt. In this case, you will also have to

   122     link to plugins statically. You can use QLibrary if you need to

   123     load dynamic libraries in a statically linked application.

   124 

   125     \note In Symbian the plugin stub files must be used whenever a

   126     path to plugin is needed. For the purposes of loading plugins,

   127     the stubs can be considered to have the same name as the actual

   128     plugin binary. In practice they have ".qtplugin" extension

   129     instead of ".dll", but this difference is handled transparently

   130     by QPluginLoader and QLibrary to avoid need for Symbian specific

   131     plugin handling in most Qt applications. Plugin stubs are needed

   132     because Symbian Platform Security denies all access to the directory

   133     where the actual plugin binaries are located.

   134 

   135     \sa QLibrary, {Plug & Paint Example}

   136 */

   137 

   138 /*!

   139     Constructs a plugin loader with the given \a parent.

   140 */

   141 QPluginLoader::QPluginLoader(QObject *parent)

   142     : QObject(parent), d(0), did_load(false)

   143 {

   144 }

   145 

   146 /*!

   147     Constructs a plugin loader with the given \a parent that will

   148     load the plugin specified by \a fileName.

   149 

   150     To be loadable, the file's suffix must be a valid suffix for a

   151     loadable library in accordance with the platform, e.g. \c .so on

   152     Unix, - \c .dylib on Mac OS X, and \c .dll on Windows. The suffix

   153     can be verified with QLibrary::isLibrary().

   154 

   155     Note: In Symbian the \a fileName must point to plugin stub file.

   156 

   157     \sa setFileName()

   158 */

   159 QPluginLoader::QPluginLoader(const QString &fileName, QObject *parent)

   160     : QObject(parent), d(0), did_load(false)

   161 {

   162     setFileName(fileName);

   163 }

   164 

   165 /*!

   166     Destroys the QPluginLoader object.

   167 

   168     Unless unload() was called explicitly, the plugin stays in memory

   169     until the application terminates.

   170 

   171     \sa isLoaded(), unload()

   172 */

   173 QPluginLoader::~QPluginLoader()

   174 {

   175     if (d)

   176         d->release();

   177 }

   178 

   179 /*!

   180     Returns the root component object of the plugin. The plugin is

   181     loaded if necessary. The function returns 0 if the plugin could

   182     not be loaded or if the root component object could not be

   183     instantiated.

   184 

   185     If the root component object was destroyed, calling this function

   186     creates a new instance.

   187 

   188     The root component, returned by this function, is not deleted when

   189     the QPluginLoader is destroyed. If you want to ensure that the root

   190     component is deleted, you should call unload() as soon you don't

   191     need to access the core component anymore.  When the library is

   192     finally unloaded, the root component will automatically be deleted.

   193 

   194     The component object is a QObject. Use qobject_cast() to access

   195     interfaces you are interested in.

   196 

   197     \sa load()

   198 */

   199 QObject *QPluginLoader::instance()

   200 {

   201     if (!load())

   202         return 0;

   203     if (d->instance)

   204         return d->instance();

   205     return 0;

   206 }

   207 

   208 /*!

   209     Loads the plugin and returns true if the plugin was loaded

   210     successfully; otherwise returns false. Since instance() always

   211     calls this function before resolving any symbols it is not

   212     necessary to call it explicitly. In some situations you might want

   213     the plugin loaded in advance, in which case you would use this

   214     function.

   215 

   216     \sa unload()

   217 */

   218 bool QPluginLoader::load()

   219 {

   220     if (!d || d->fileName.isEmpty())

   221         return false;

   222     if (did_load)

   223         return d->pHnd && d->instance;

   224     if (!d->isPlugin())

   225         return false;

   226     did_load = true;

   227     return d->loadPlugin();

   228 }

   229 

   230 

   231 /*!

   232     Unloads the plugin and returns true if the plugin could be

   233     unloaded; otherwise returns false.

   234 

   235     This happens automatically on application termination, so you

   236     shouldn't normally need to call this function.

   237 

   238     If other instances of QPluginLoader are using the same plugin, the

   239     call will fail, and unloading will only happen when every instance

   240     has called unload().

   241 

   242     Don't try to delete the root component. Instead rely on

   243     that unload() will automatically delete it when needed.

   244 

   245     \sa instance(), load()

   246 */

   247 bool QPluginLoader::unload()

   248 {

   249     if (did_load) {

   250         did_load = false;

   251         return d->unload();

   252     }

   253     if (d)  // Ouch

   254         d->errorString = tr("The plugin was not loaded.");

   255     return false;

   256 }

   257 

   258 /*!

   259     Returns true if the plugin is loaded; otherwise returns false.

   260 

   261     \sa load()

   262  */

   263 bool QPluginLoader::isLoaded() const

   264 {

   265     return d && d->pHnd && d->instance;

   266 }

   267 

   268 /*!

   269     \property QPluginLoader::fileName

   270     \brief the file name of the plugin

   271 

   272     To be loadable, the file's suffix must be a valid suffix for a

   273     loadable library in accordance with the platform, e.g. \c .so on

   274     Unix, \c .dylib on Mac OS X, and \c .dll on Windows. The suffix

   275     can be verified with QLibrary::isLibrary().

   276 

   277     If the file name does not exist, it will not be set. This property

   278     will then contain an empty string.

   279 

   280     By default, this property contains an empty string.

   281 

   282     Note: In Symbian the \a fileName must point to plugin stub file.

   283 

   284     \sa load()

   285 */

   286 void QPluginLoader::setFileName(const QString &fileName)

   287 {

   288 #if defined(QT_SHARED)

   289     QLibrary::LoadHints lh;

   290     if (d) {

   291         lh = d->loadHints;

   292         d->release();

   293         d = 0;

   294         did_load = false;

   295     }

   296 

   297 #if defined(Q_OS_SYMBIAN)

   298     // In Symbian we actually look for plugin stub, so modify the filename

   299     // to make canonicalFilePath find the file, if .dll is specified.

   300     QFileInfo fi(fileName);

   301 

   302     if (fi.suffix() == QLatin1String("dll")) {

   303         QString stubName = fileName;

   304         stubName.chop(3);

   305         stubName += QLatin1String("qtplugin");

   306         fi = QFileInfo(stubName);

   307     }

   308 

   309     QString fn = fi.canonicalFilePath();

   310     // If not found directly, check also all the available drives

   311     if (!fn.length()) {

   312         QString stubPath(fi.fileName().length() ? fi.absoluteFilePath() : QString());

   313         if (stubPath.length() > 1) {

   314             if (stubPath.at(1).toAscii() == ':')

   315                 stubPath.remove(0,2);

   316             QFileInfoList driveList(QDir::drives());

   317             RFs rfs = qt_s60GetRFs();

   318             foreach(const QFileInfo& drive, driveList) {

   319                 QString testFilePath(drive.absolutePath() + stubPath);

   320                 testFilePath = QDir::cleanPath(testFilePath);

   321                 // Use native Symbian code to check for file existence, because checking

   322                 // for file from under non-existent protected dir like E:/private/<uid> using

   323                 // QFile::exists causes platform security violations on most apps.

   324                 QString nativePath = QDir::toNativeSeparators(testFilePath);

   325                 TPtrC ptr(qt_QString2TPtrC(nativePath));

   326                 TUint attributes;

   327                 TInt err = rfs.Att(ptr, attributes);

   328                 if (err == KErrNone) {

   329                     fn = testFilePath;

   330                     break;

   331                 }

   332             }

   333         }

   334     }

   335 

   336 #else

   337     QString fn = QFileInfo(fileName).canonicalFilePath();

   338 #endif

   339 

   340     d = QLibraryPrivate::findOrCreate(fn);

   341     d->loadHints = lh;

   342     if (fn.isEmpty())

   343         d->errorString = QLibrary::tr("The shared library was not found.");

   344 #else

   345     if (qt_debug_component()) {

   346         qWarning("Cannot load %s into a statically linked Qt library.",

   347             (const char*)QFile::encodeName(fileName));

   348     }

   349     Q_UNUSED(fileName);

   350 #endif

   351 }

   352 

   353 QString QPluginLoader::fileName() const

   354 {

   355     if (d)

   356         return d->fileName;

   357     return QString();

   358 }

   359 

   360 /*!

   361     \since 4.2

   362 

   363     Returns a text string with the description of the last error that occurred.

   364 */

   365 QString QPluginLoader::errorString() const

   366 {

   367     return (!d || d->errorString.isEmpty()) ? tr("Unknown error") : d->errorString;

   368 }

   369 

   370 typedef QList<QtPluginInstanceFunction> StaticInstanceFunctionList;

   371 Q_GLOBAL_STATIC(StaticInstanceFunctionList, staticInstanceFunctionList)

   372 

   373 /*! \since 4.4

   374 

   375     \property QPluginLoader::loadHints

   376     \brief Give the load() function some hints on how it should behave.

   377 

   378     You can give hints on how the symbols in the plugin are

   379     resolved. By default, none of the hints are set.

   380 

   381     See the documentation of QLibrary::loadHints for a complete

   382     description of how this property works.

   383 

   384     \sa QLibrary::loadHints

   385 */

   386 

   387 void QPluginLoader::setLoadHints(QLibrary::LoadHints loadHints)

   388 {

   389     if (!d) {

   390         d = QLibraryPrivate::findOrCreate(QString());   // ugly, but we need a d-ptr

   391         d->errorString.clear();

   392     }

   393     d->loadHints = loadHints;

   394 }

   395 

   396 QLibrary::LoadHints QPluginLoader::loadHints() const

   397 {

   398     if (!d) {

   399         QPluginLoader *that = const_cast<QPluginLoader *>(this);

   400         that->d = QLibraryPrivate::findOrCreate(QString());   // ugly, but we need a d-ptr

   401         that->d->errorString.clear();

   402     }

   403     return d->loadHints;

   404 }

   405 

   406 /*!

   407     \relates QPluginLoader

   408     \since 4.4

   409 

   410     Registers the given \a function with the plugin loader.

   411 */

   412 void Q_CORE_EXPORT qRegisterStaticPluginInstanceFunction(QtPluginInstanceFunction function)

   413 {

   414     staticInstanceFunctionList()->append(function);

   415 }

   416 

   417 /*!

   418     Returns a list of static plugin instances (root components) held

   419     by the plugin loader.

   420 */

   421 QObjectList QPluginLoader::staticInstances()

   422 {

   423     QObjectList instances;

   424     StaticInstanceFunctionList *functions = staticInstanceFunctionList();

   425     if (functions) {

   426         for (int i = 0; i < functions->count(); ++i)

   427             instances.append((*functions)[i]());

   428     }

   429     return instances;

   430 }

   431 

   432 QT_END_NAMESPACE

   433 

   434 #endif // QT_NO_LIBRARY