QPluginLoader Class Reference

The QPluginLoader class loads a plugin at run-time. More...

#include <qpluginloader.h>

Inheritance diagram for QPluginLoader:

Public Functions
QString	errorString () const
	Returns a text string with the description of the last error that occurred. More...
QString	fileName () const
QObject *	instance ()
	Returns the root component object of the plugin. More...
bool	isLoaded () const
	Returns true if the plugin is loaded; otherwise returns false. More...
bool	load ()
	Loads the plugin and returns true if the plugin was loaded successfully; otherwise returns false. More...
QLibrary::LoadHints	loadHints () const
	QPluginLoader (QObject *parent=0)
	Constructs a plugin loader with the given parent. More...
	QPluginLoader (const QString &fileName, QObject *parent=0)
	Constructs a plugin loader with the given parent that will load the plugin specified by fileName. More...
void	setFileName (const QString &fileName)
void	setLoadHints (QLibrary::LoadHints loadHints)
bool	unload ()
	Unloads the plugin and returns true if the plugin could be unloaded; otherwise returns false. More...
	~QPluginLoader ()
	Destroys the QPluginLoader object. More...
Public Functions inherited from QObject
bool	blockSignals (bool b)
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it). More...
const QObjectList &	children () const
	Returns a list of child objects. More...
bool	connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
bool	disconnect (const char *signal=0, const QObject *receiver=0, const char *member=0)
bool	disconnect (const QObject *receiver, const char *member=0)
void	dumpObjectInfo ()
	Dumps information about signal connections, etc. More...
void	dumpObjectTree ()
	Dumps a tree of children to the debug output. More...
QList< QByteArray >	dynamicPropertyNames () const
	Returns the names of all properties that were dynamically added to the object using setProperty(). More...
virtual bool	event (QEvent *)
	This virtual function receives events to an object and should return true if the event e was recognized and processed. More...
virtual bool	eventFilter (QObject *, QEvent *)
	Filters events if this object has been installed as an event filter for the watched object. More...
template<typename T >
T	findChild (const QString &aName=QString()) const
	Returns the child of this object that can be cast into type T and that is called name, or 0 if there is no such object. More...
template<typename T >
QList< T >	findChildren (const QString &aName=QString()) const
	Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects. More...
template<typename T >
QList< T >	findChildren (const QRegExp &re) const
bool	inherits (const char *classname) const
	Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false. More...
void	installEventFilter (QObject *)
	Installs an event filter filterObj on this object. More...
bool	isWidgetType () const
	Returns true if the object is a widget; otherwise returns false. More...
void	killTimer (int id)
	Kills the timer with timer identifier, id. More...
virtual const QMetaObject *	metaObject () const
	Returns a pointer to the meta-object of this object. More...
void	moveToThread (QThread *thread)
	Changes the thread affinity for this object and its children. More...
QString	objectName () const
QObject *	parent () const
	Returns a pointer to the parent object. More...
QVariant	property (const char *name) const
	Returns the value of the object's name property. More...
Q_INVOKABLE	QObject (QObject *parent=0)
	Constructs an object with parent object parent. More...
void	removeEventFilter (QObject *)
	Removes an event filter object obj from this object. More...
void	setObjectName (const QString &name)
void	setParent (QObject *)
	Makes the object a child of parent. More...
bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value. More...
void	setUserData (uint id, QObjectUserData *data)
bool	signalsBlocked () const
	Returns true if signals are blocked; otherwise returns false. More...
int	startTimer (int interval)
	Starts a timer and returns a timer identifier, or returns zero if it could not start a timer. More...
QThread *	thread () const
	Returns the thread in which the object lives. More...
QObjectUserData *	userData (uint id) const
virtual	~QObject ()
	Destroys the object, deleting all its child objects. More...

Static Public Functions
static QObjectList	staticInstances ()
	Returns a list of static plugin instances (root components) held by the plugin loader. More...
Static Public Functions inherited from QObject
static bool	connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
	Creates a connection of the given type from the signal in the sender object to the method in the receiver object. More...
static bool	connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
static bool	disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
	Disconnects signal in object sender from method in object receiver. More...
static bool	disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
static uint	registerUserData ()
static QString	tr (const char *sourceText, const char *comment=0, int n=-1)
static QString	trUtf8 (const char *sourceText, const char *comment=0, int n=-1)

Properties
QLibraryPrivate *	d
bool	did_load
QString	fileName
	the file name of the plugin More...
QLibrary::LoadHints	loadHints
	Give the load() function some hints on how it should behave. More...

Related Functions
(Note that these are not member functions.)
void Q_CORE_EXPORT	qRegisterStaticPluginInstanceFunction (QtPluginInstanceFunction function)
	Registers the given function with the plugin loader. More...
Related Functions inherited from QObject
T	qFindChildqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QRegExp &regExp)()
T *	qobject_cast (QObject *object)
	QObjectList
void *	qt_find_obj_child (QObject *parent, const char *type, const QString &name)
	Returns a pointer to the object named name that inherits type and with a given parent. More...

Additional Inherited Members
Public Slots inherited from QObject
void	deleteLater ()
	Schedules this object for deletion. More...
Signals inherited from QObject
void	destroyed (QObject *=0)
	This signal is emitted immediately before the object obj is destroyed, and can not be blocked. More...
Static Public Variables inherited from QObject
static const QMetaObject	staticMetaObject
	This variable stores the meta-object for the class. More...
Protected Functions inherited from QObject
virtual void	childEvent (QChildEvent *)
	This event handler can be reimplemented in a subclass to receive child events. More...
virtual void	connectNotify (const char *signal)
	This virtual function is called when something has been connected to signal in this object. More...
virtual void	customEvent (QEvent *)
	This event handler can be reimplemented in a subclass to receive custom events. More...
virtual void	disconnectNotify (const char *signal)
	This virtual function is called when something has been disconnected from signal in this object. More...
	QObject (QObjectPrivate &dd, QObject *parent=0)
int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal. More...
QObject *	sender () const
	Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns 0. More...
int	senderSignalIndex () const
virtual void	timerEvent (QTimerEvent *)
	This event handler can be reimplemented in a subclass to receive timer events for the object. More...
Protected Variables inherited from QObject
QScopedPointer< QObjectData >	d_ptr
Static Protected Variables inherited from QObject
static const QMetaObject	staticQtMetaObject

Detailed Description

The QPluginLoader class loads a plugin at run-time.

Note

This class or function is reentrant.

QPluginLoader provides access to a 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:

• QPluginLoader checks that a plugin is linked against the same version of Qt as the application.
• QPluginLoader provides direct access to a root component object (instance()), instead of forcing you to resolve a C function manually.

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 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.

See also

QLibrary, {Plug & Paint Example}

Definition at line 62 of file qpluginloader.h.

Constructors and Destructors

QPluginLoader() [1/2]

QPluginLoader::QPluginLoader ( QObject *  parent = 0 )

explicit

Constructs a plugin loader with the given parent.

Definition at line 144 of file qpluginloader.cpp.

    : QObject(parent), d(0), did_load(false)
{
}

QPluginLoader() [2/2]

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

explicit

Constructs a plugin loader with the given parent that will load the plugin specified by fileName.

To be loadable, the file's suffix must be a valid suffix for a loadable library in accordance with the platform, e.g. .so on Unix, - .dylib on Mac OS X, and .dll on Windows. The suffix can be verified with QLibrary::isLibrary().

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

See also

setFileName()

Definition at line 162 of file qpluginloader.cpp.

    : QObject(parent), d(0), did_load(false)
{
    setFileName(fileName);
}

~QPluginLoader()

QPluginLoader::~QPluginLoader

(

)

Destroys the QPluginLoader object.

Unless unload() was called explicitly, the plugin stays in memory until the application terminates.

See also

isLoaded(), unload()

Definition at line 176 of file qpluginloader.cpp.

{
    if (d)
        d->release();
}

Functions

errorString()

QString QPluginLoader::errorString

(

)

const

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

Since

4.2

Definition at line 374 of file qpluginloader.cpp.

Referenced by QDeclarativeImportDatabase::importPlugin().

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

fileName()

QString QPluginLoader::fileName

(

)

const

Referenced by setFileName().

instance()

QObject * QPluginLoader::instance

(

)

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.

See also

load()

Definition at line 202 of file qpluginloader.cpp.

Referenced by QScriptEngine::availableExtensions(), QScriptEngine::importExtension(), QDeclarativeImportDatabase::importPlugin(), QDeclarativeDebugServerPrivate::loadConnectionPlugin(), and QDeclarativeInspectorService::loadInspectorPlugin().

{
    if (!load())
        return 0;
    if (!d->inst && d->instance)
        d->inst = d->instance();
    return d->inst.data();
}

isLoaded()

bool QPluginLoader::isLoaded

(

)

const

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

See also

load()

Definition at line 266 of file qpluginloader.cpp.

{
    return d && d->pHnd && d->instance;
}

load()

bool QPluginLoader::load

(

)

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.

See also

unload()

Definition at line 221 of file qpluginloader.cpp.

Referenced by QDeclarativeImportDatabase::importPlugin(), instance(), QDeclarativeDebugServerPrivate::loadConnectionPlugin(), and QDeclarativeInspectorService::loadInspectorPlugin().

{
    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();
}

loadHints()

QLibrary::LoadHints QPluginLoader::loadHints

(

)

const

setFileName()

void QPluginLoader::setFileName

(

const QString &

fileName

)

Definition at line 292 of file qpluginloader.cpp.

Referenced by QDeclarativeDebugServerPrivate::loadConnectionPlugin(), and QPluginLoader().

{
#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
}

setLoadHints()

void QPluginLoader::setLoadHints

(

QLibrary::LoadHints

loadHints

)

Definition at line 399 of file qpluginloader.cpp.

{
    if (!d) {
        d = QLibraryPrivate::findOrCreate(QString());   // ugly, but we need a d-ptr
        d->errorString.clear();
    }
    d->loadHints = loadHints;
}

staticInstances()

QObjectList QPluginLoader::staticInstances ( )

static

Returns a list of static plugin instances (root components) held by the plugin loader.

Definition at line 436 of file qpluginloader.cpp.

Referenced by QScriptEngine::availableExtensions(), QScriptEngine::importExtension(), QFactoryLoader::instance(), and QFactoryLoader::keys().

{
    QObjectList instances;
    StaticInstanceFunctionList *functions = staticInstanceFunctionList();
    if (functions) {
        for (int i = 0; i < functions->count(); ++i)
            instances.append((*functions)[i]());
    }
    return instances;
}

unload()

bool QPluginLoader::unload

(

)

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.

See also

instance(), load()

Definition at line 250 of file qpluginloader.cpp.

Referenced by QDeclarativeDebugServerPrivate::loadConnectionPlugin(), and QDeclarativeInspectorService::loadInspectorPlugin().

{
    if (did_load) {
        did_load = false;
        return d->unload();
    }
    if (d)  // Ouch
        d->errorString = tr("The plugin was not loaded.");
    return false;
}

Friends and Related Functions

qRegisterStaticPluginInstanceFunction()

void Q_CORE_EXPORT qRegisterStaticPluginInstanceFunction ( QtPluginInstanceFunction  function )

related

Registers the given function with the plugin loader.

Since

4.4

Definition at line 427 of file qpluginloader.cpp.

{
    staticInstanceFunctionList()->append(function);
}

Properties

d

QLibraryPrivate* QPluginLoader::d

private

Definition at line 89 of file qpluginloader.h.

Referenced by errorString(), instance(), isLoaded(), load(), setFileName(), unload(), and ~QPluginLoader().

did_load

bool QPluginLoader::did_load

private

Definition at line 90 of file qpluginloader.h.

Referenced by load(), setFileName(), and unload().

fileName

QString QPluginLoader::fileName

private

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. .so on Unix, .dylib on Mac OS X, and .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 fileName must point to plugin stub file.

See also

load()

Definition at line 65 of file qpluginloader.h.

loadHints

QLibrary::LoadHints QPluginLoader::loadHints

private

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

Since

4.4

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.

See also

QLibrary::loadHints

Definition at line 66 of file qpluginloader.h.

---

The documentation for this class was generated from the following files:

• /src/corelib/plugin/qpluginloader.h
• /src/corelib/plugin/qpluginloader.cpp