QLibrary Class Reference
[QtCore module]

Detailed Description

The QLibrary class loads shared libraries at runtime.

An instance of a QLibrary object operates on a single shared object file (which we call a "library", but is also known as a "DLL"). A QLibrary provides access to the functionality in the library in a platform independent way. You can either pass a file name in the constructor, or set it explicitly with setFileName(). When loading the library, QLibrary searches in all the system-specific library locations (e.g. LD_LIBRARY_PATH on Unix), unless the file name has an absolute path. If the file cannot be found, QLibrary tries the name with different platform-specific file suffixes, like ".so" on Unix, ".dylib" on the Mac, or ".dll" on Windows and Symbian. This makes it possible to specify shared libraries that are only identified by their basename (i.e. without their suffix), so the same code will work on different operating systems.

The most important functions are load() to dynamically load the library file, isLoaded() to check whether loading was successful, and resolve() to resolve a symbol in the library. The resolve() function implicitly tries to load the library if it has not been loaded yet. Multiple instances of QLibrary can be used to access the same physical library. Once loaded, libraries remain in memory until the application terminates. You can attempt to unload a library using unload(), but if other instances of QLibrary are using the same library, the call will fail, and unloading will only happen when every instance has called unload().

A typical use of QLibrary is to resolve an exported symbol in a library, and to call the C 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 executable against a library.

Note: In Symbian resolving symbols using their names is supported only if the library is built as STDDLL. Otherwise ordinals must be used. Also, in Symbian the path of the library is ignored and system default library location is always used.

The following code snippet loads a library, resolves the symbol "mysymbol", and calls the function if everything succeeded. If something goes wrong, e.g. the library file does not exist or the symbol is not defined, the function pointer will be 0 and won't be called.

 QLibrary myLib("mylib");
 typedef void (*MyPrototype)();
 MyPrototype myFunction = (MyPrototype) myLib.resolve("mysymbol");
 if (myFunction)
     myFunction();

The symbol must be exported as a C function from the library for resolve() to work. This means that the function must be wrapped in an extern "C" block if the library is compiled with a C++ compiler. On Windows, this also requires the use of a dllexport macro; see resolve() for the details of how this is done. For convenience, there is a static resolve() function which you can use if you just want to call a function in a library without explicitly loading the library first:

 typedef void (*MyPrototype)();
 MyPrototype myFunction =
         (MyPrototype) QLibrary::resolve("mylib", "mysymbol");
 if (myFunction)
     myFunction();

See also QPluginLoader.

Member Type Documentation

 typedef int (*AvgFunction)(int, int);

 AvgFunction avg = (AvgFunction) library->resolve("avg");
 if (avg)
     return avg(5, 8);
 else
     return -1;

 extern "C" MY_EXPORT int avg(int a, int b)
 {
     return (a + b) / 2;
 }

 #ifdef Q_WS_WIN
 #define MY_EXPORT __declspec(dllexport)
 #else
 #define MY_EXPORT
 #endif