From bd0f3345a938b35ce6a12f6150373b0955b8dd12 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Sun, 10 Jul 2011 15:24:15 -0500 Subject: Add Qt3 development HEAD version --- doc/html/qlibrary.html | 290 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 290 insertions(+) create mode 100644 doc/html/qlibrary.html (limited to 'doc/html/qlibrary.html') diff --git a/doc/html/qlibrary.html b/doc/html/qlibrary.html new file mode 100644 index 0000000..19a1878 --- /dev/null +++ b/doc/html/qlibrary.html @@ -0,0 +1,290 @@ + + + + + +QLibrary Class + + + + + + + +

QLibrary Class Reference

+ +

The QLibrary class provides a wrapper for handling shared libraries. +More... +

All the functions in this class are reentrant when Qt is built with thread support.

#include <qlibrary.h> +

List of all member functions. +

Public Members

QLibrary ( const QString & filename )
virtual ~QLibrary ()
void * resolve ( const char * symb )
bool load ()
virtual bool unload ()
bool isLoaded () const
bool autoUnload () const
void setAutoUnload ( bool enabled )
QString library () const

Static Public Members

void * resolve ( const QString & filename, const char * symb )

Detailed Description

+ + + +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 ensures that the shared library is loaded and stays in +memory whilst it is in use. QLibrary can also unload the library +on destruction and release unused resources. +

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

The following code snippet loads a library, resolves the symbol +"mysymbol", and calls the function if everything succeeded. If +something went 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. When the QLibrary object is destroyed the library will be +unloaded, making all references to memory allocated in the library +invalid. +

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

+ +

Member Function Documentation

QLibrary::QLibrary ( const QString & filename ) +

+Creates a QLibrary object for the shared library filename. The +library will be unloaded in the destructor. +

Note that filename does not need to include the (platform specific) +file extension, so calling +

+    QLibrary lib( "mylib" );
+

+ +is equivalent to calling +

+    QLibrary lib( "mylib.dll" );
+

+ +on Windows, and +

+    QLibrary lib( "libmylib.so" );
+

+ +on Unix. Specifying the extension is not recommended, since +doing so introduces a platform dependency. +

If filename does not include a path, the library loader will +look for the file in the platform specific search paths. +

See also load(), unload(), and setAutoUnload(). + +

QLibrary::~QLibrary () `[virtual]` +

+Deletes the QLibrary object. +

The library will be unloaded if autoUnload() is TRUE (the +default), otherwise it stays in memory until the application +exits. +

See also unload() and setAutoUnload(). + +

bool QLibrary::autoUnload () const +

+Returns TRUE if the library will be automatically unloaded when +this wrapper object is destructed; otherwise returns FALSE. The +default is TRUE. +

bool QLibrary::isLoaded () const +

+Returns TRUE if the library is loaded; otherwise returns FALSE. +

QString QLibrary::library () const +

+Returns the filename of the shared library this QLibrary object +handles, including the platform specific file extension. +

For example: +

+    QLibrary lib( "mylib" );
+    QString str = lib.library();
+

+ +will set str to "mylib.dll" on Windows, and "libmylib.so" on Linux. + +

bool QLibrary::load () +

+Loads the library. Since resolve() always calls this function +before resolving any symbols it is not necessary to call it +explicitly. In some situations you might want the library loaded +in advance, in which case you would use this function. +

On Darwin and Mac OS X this function uses code from dlcompat, part of the +OpenDarwin project. +

Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: +

The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. +

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +

void * QLibrary::resolve ( const char * symb ) +

+Returns the address of the exported symbol symb. The library is +loaded if necessary. The function returns 0 if the symbol could +not be resolved or the library could not be loaded. +

+    typedef int (*avgProc)( int, int );
+
+    avgProc avg = (avgProc) library->resolve( "avg" );
+    if ( avg )
+        return avg( 5, 8 );
+    else
+        return -1;
+

+ +

The symbol must be exported as a C-function from the library. This +requires the extern "C" notation if the library is compiled +with a C++ compiler. On Windows you also have to explicitly export +the function from the DLL using the __declspec(dllexport) +compiler directive. +

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

+ +

with MY_EXPORT defined as +

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

+ +

On Darwin and Mac OS X this function uses code from dlcompat, part of the +OpenDarwin project. +

The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. +

void * QLibrary::resolve ( const QString & filename, const char * symb ) `[static]` +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Loads the library filename and returns the address of the +exported symbol symb. Note that like the constructor, filename does not need to include the (platform specific) file +extension. The library remains loaded until the process exits. +

The function returns 0 if the symbol could not be resolved or the +library could not be loaded. +

This function is useful only if you want to resolve a single +symbol, e.g. a function pointer from a specific library once: +

+    typedef void (*FunctionType)();
+    static FunctionType *ptrFunction = 0;
+    static bool triedResolve = FALSE;
+    if ( !ptrFunction && !triedResolve )
+        ptrFunction = QLibrary::resolve( "mylib", "mysymb" );
+
+    if ( ptrFunction )
+        ptrFunction();
+    else
+        ...
+

+ +

If you want to resolve multiple symbols, use a QLibrary object and +call the non-static version of resolve(). +

void QLibrary::setAutoUnload ( bool enabled ) +

+If enabled is TRUE (the default), the wrapper object is set to +automatically unload the library upon destruction. If enabled +is FALSE, the wrapper object is not unloaded unless you explicitly +call unload(). +

bool QLibrary::unload () `[virtual]` +

+Unloads the library and returns TRUE if the library could be +unloaded; otherwise returns FALSE. +

This function is called by the destructor if autoUnload() is +enabled. +