![]() |
| ||
Classes - Annotated - Tree - Functions - Home - Structure |
The QLibrary class provides a wrapper for handling shared libraries. More...
#include <qlibrary.h>
The QLibrary class provides a wrapper for handling shared libraries.
An instance of a QLibrary object can handle a single shared library and provide access to the functionality in the library in a platform independent way. If the library is a component server, QLibrary provides access to the exported component and can directly query this component for interfaces.
QLibrary makes sure that the shared library is loaded and stays in memory for the time it is being used, and can also unload the library upon destruction and thus release unused resources.
A typical use of QLibrary is to resolve an exported symbol in a shared object, and to e.g. call the function that this symbol represents. This is called "explicit linking" in contrast to "implicit linking", which is done by the link step in the build process when linking an binary against a library.
The following code snipplet will load a library, resolve the symbol "mysymbol", and call the function if everything succeeded. If anything went wrong, e.g. the library file is not existing, or the symbol is not defined, the function pointer will become a null pointer. Upon destruction of the QLibrary object the library will be unloaded again, making all referenced to memory allocated in the library invalid.
typedef void (*MyPrototype)(); MyPrototype myFunction; QLibrary myLib( "mylib" ); myFunction = (MyProtoype)myLib.resolve( "mysymbol" ); if ( myFunction ) { myFunction(); }
Using this mechanism is only safe when the correct type of the function in the shared object is guaranteed - a wrong type might crash the application or leave it in an unstable state. Keeping a reference to the function pointer is also dangerous, as the library might be unloaded.
A safe and thus commonly used architecture for explicit linking of symbols is to use interfaces and components. QLibrary supports the component model in Qt with the queryInterface function.
MySpecialInterface *iface = 0; QLibrary myLib( "mylib" ); if ( myLib.queryInterface( IID_MySpecial, (QUnknownInterface**)&iface ) == QS_OK ) { iface->myFunction(); iface->release(); }
The shared object "mylib", which now acts as a component server, is guaranteed to provide a pointer to the correct interface type, so that it becomes safe to use unknown libraries in an application.
This enum type defines the various policies a QLibrary can have with respect to loading and unloading the shared library.
The policy can be:
Note that filename does not need to include the (platform specific) file extension, so calling
QLibrary lib( "mylib" );
would be equivalent to
QLibrary lib( "mylib.dll" );
on Windows. But "mylib.dll" will obviously not work on other platforms.
See also setPolicy() and unload().
See also unload() and setPolicy().
See also unload.
QLibrary lib( "mylib" ); QString str = lib.library();
will set str to "mylib.dll" on Windows, and "libmylib.so" on Linux.
See also setPolicy.
See also QUnknownInterface::queryInterface.
typedef int (*addProc)( int, int ); addProc add = (addProc) library->resolve( "add" ); if ( add ) return add( 5, 8 ); else return 5 + 8;
See also queryInterface.
See also LibraryPolicy.
This function gets called automatically in the destructor if the policy is not Manual.
Warning: If force is set to TRUE, the library gets unloaded at any cost, which is in most cases a segmentation fault, so you should know what you're doing!
See also queryInterface and resolve.
Search the documentation, FAQ, qt-interest archive and more (uses
www.trolltech.com):
This file is part of the Qt toolkit, copyright © 1995-2001 Trolltech, all rights reserved.
Copyright © 2001 Trolltech | Trademarks | Qt version 3.0.0-beta2
|