Main Page   Namespace List   Class Hierarchy   Compound List   File List   Namespace Members   Compound Members   File Members  

qlibrary.h

Go to the documentation of this file.
00001 /****************************************************************************
00002  ** $Id:  qt/qlibrary.h   3.0.0   edited Sep 20 19:46 $
00003  **
00004  ** Definition of QLibrary class
00005  **
00006  ** Created : 2000-01-01
00007  **
00008  ** Copyright (C) 2000 Trolltech AS.  All rights reserved.
00009  **
00010  ** This file is part of the kernel module of the Qt GUI Toolkit.
00011  **
00012  ** This file may be distributed under the terms of the Q Public License
00013  ** as defined by Trolltech AS of Norway and appearing in the file
00014  ** LICENSE.QPL included in the packaging of this file.
00015  **
00016  ** This file may be distributed and/or modified under the terms of the
00017  ** GNU General Public License version 2 as published by the Free Software
00018  ** Foundation and appearing in the file LICENSE.GPL included in the
00019  ** packaging of this file.
00020  **
00021  ** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
00022  ** licenses may use this file in accordance with the Qt Commercial License
00023  ** Agreement provided with the Software.
00024  **
00025  ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
00026  ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
00027  **
00028  ** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
00029  **       information about Qt Commercial License Agreements.
00030  ** See http://www.trolltech.com/qpl/ for QPL licensing information.
00031  ** See http://www.trolltech.com/gpl/ for GPL licensing information.
00032  **
00033  ** Contact info@trolltech.com if any conditions of this licensing are
00034  ** not clear to you.
00035  **
00036  **     Modified by BJDC, Motorola 
00037  **
00038  **********************************************************************/
00039 
00040 #ifndef QLIBRARY_H
00041 #define QLIBRARY_H
00042 
00043 #ifndef QT_H
00044 #include <qstring.h>
00045 #endif // QT_H
00046 
00047 #ifndef QT_NO_COMPONENT
00048 
00049 #include "qcom.h"
00050 //#include "quuid.h"
00051 
00052 class QLibraryPrivate;
00053 
00054 /**
00055  * The QLibrary class provides a wrapper for handling shared libraries.
00056  *
00057  * An instance of a QLibrary object can handle a single shared library and
00058  * provide access to the functionality in the library in a platform independent way.
00059  * If the library is a component server, QLibrary provides access to the exported
00060  * component and can directly query this component for interfaces.
00061  *
00062  * QLibrary ensures that the shared library is loaded and stays in memory whilst it is
00063  * in use. QLibrary can also unload the library on destruction and release unused resources.
00064  *
00065  * A typical use of QLibrary is to resolve an exported symbol in a shared object, and to
00066  * call the function that this symbol represents. This is called "explicit linking"
00067  * in contrast to "implicit linking", which is done by the link step in the build process
00068  * when linking an executable against a library.
00069  *
00070  * The following code snippet loads a library, resolves the symbol "mysymbol", and calls
00071  * the function if everything succeeded. If something went wrong, e.g. the library file
00072  * does not exist or the symbol is not defined, the function pointer will be 0 and won't
00073  * be called. When the QLibrary object is destroyed the library will be unloaded, making
00074  * all references to memory allocated in the library invalid.
00075  *
00076  * @code
00077  * typedef void (*MyPrototype)();
00078  * MyPrototype myFunction;
00079  *
00080  * QLibrary myLib( "mylib" );
00081  * myFunction = (MyProtoype) myLib.resolve( "mysymbol" );
00082  * if ( myFunction )
00083  * {
00084  *        myFunction();
00085  * }
00086  * @endcode
00087  */
00088 
00089 class Q_EXPORT QLibrary
00090 {
00091 public:
00092         
00093         /**
00094          * Constructor of QLibrary
00095          *
00096          * Creates a QLibrary object for the shared library filename. The library will be
00097          * unloaded in the destructor.
00098          *
00099          * @see load(), unload(), and setAutoUnload().
00100          *
00101          * @note that filename does not need to include the (platform specific) file extension,
00102          * so calling:
00103          *              QLibrary lib( "mylib" );
00104          * is equivalent to calling:
00105          *              QLibrary lib( "mylib.dll" );
00106          *
00107          * If filename does not include a path, the library loader will look for the file in
00108          * the platform specific search paths.
00109          */
00110         QLibrary( const QString& filename );
00111 
00112         /**
00113          * Deletes the QLibrary object.
00114          *
00115          * The library will be unloaded if autoUnload() is TRUE (the default),
00116          * otherwise it stays in memory until the application exits.
00117          *
00118          * @see unload() and setAutoUnload().
00119          */
00120         virtual ~QLibrary();
00121 
00122         /**
00123          * Returns the address of the exported symbol symb. The library is loaded if
00124          * necessary. The function returns 0 if the symbol could not be resolved or
00125          * the library could not be loaded.
00126          *
00127          *@code
00128          * typedef int (*avgProc)( int, int );
00129          *
00130          * avgProc avg = (avgProc) library->resolve( "avg" );
00131          * if ( avg )
00132          * {
00133          *         return avg( 5, 8 );
00134          * }
00135          * else
00136          * {
00137          *         return -1;
00138          *      }
00139          * @endcode
00140          *
00141          */
00142         void *resolve( const char* );
00143 
00144         /**
00145          * This is an overloaded member function, provided for convenience.
00146          * It behaves essentially like the above function.
00147          * Loads the library filename and returns the address of the exported symbol symb.
00148          *
00149          * The function returns 0 if the symbol could not be resolved or the library
00150          * could not be loaded.
00151 
00152          * This function is useful only if you want to resolve a single symbol,
00153          * e.g. a function pointer from a specific library once:
00154 
00155          *@code
00156          * typedef void (*FunctionType)();
00157          * static FunctionType *ptrFunction = 0;
00158          * static bool triedResolve = FALSE;
00159          * if ( !ptrFunction && !triedResolve )
00160          *         ptrFunction = QLibrary::resolve( "mylib", "mysymb" );
00161          *
00162          * if ( ptrFunction )
00163          *              ptrFunction();
00164          * else
00165          *        ...
00166          * @endcode
00167          *        
00168          * @note that like the constructor, filename does not need to include the (platform
00169          * specific) file extension. The library remains loaded until the process exits.
00170      */
00171         static void *resolve( const QString &filename, const char * );
00172 
00173         /**
00174          * Loads the library. Since resolve() always calls this function before
00175          * resolving any symbols it is not necessary to call it explicitly. In
00176          * some situations you might want the library loaded in advance, in which
00177          * case you would use this function.
00178          */
00179         bool load();
00180 
00181         /**
00182          * Unloads the library and returns TRUE if the library could be unloaded;
00183          * otherwise returns FALSE.
00184 
00185          * This function is called by the destructor if autoUnload() is enabled.
00186          */
00187         virtual bool unload();
00188 
00189         /**
00190          * Returns TRUE if the library is loaded; otherwise returns FALSE.
00191          *
00192          * @see unload().
00193          */
00194         bool isLoaded() const;
00195 
00196         /**
00197          * Returns TRUE if the library will be automatically unloaded when
00198          * this wrapper object is destructed; otherwise returns FALSE.
00199          * The default is TRUE.
00200          */
00201         bool autoUnload() const;
00202 
00203         /**
00204          * If enabled is TRUE (the default), the wrapper object is set to automatically
00205          * unload the library upon destruction. If enabled is FALSE, the wrapper object
00206          * is not unloaded unless you explicitly call unload().
00207          */
00208         void setAutoUnload( bool enable );
00209 
00210         /**
00211          * Returns the filename of the shared library this QLibrary object handles,
00212          * including the platform specific file extension.
00213          *
00214          *@code
00215          * QLibrary lib( "mylib" );
00216          * //set str to  "libmylib.so"
00217          * QString str = lib.library();
00218          * @endcode
00219          */
00220         QString library() const;
00221 
00222         /**
00223          * Forwards the query to the component and returns the result. request and
00224          * iface are propagated to the component's queryInterface implementation.
00225          *
00226          * The library gets loaded if necessary.
00227      */
00228         QRESULT queryInterface( const QUuid& request, QUnknownInterface** iface);
00229         
00230 
00231 private:
00232         
00233         void createInstance();
00234 
00235 private:
00236         
00237         QUnknownInterface *entry;
00238         QLibraryPrivate *d;
00239         QString libfile;
00240         uint aunload : 1;
00241 
00242 #if defined(Q_DISABLE_COPY)
00243 private:  // Disabled copy constructor and operator=
00244         
00245         QLibrary( const QLibrary & );
00246         QLibrary &operator=( const QLibrary & );
00247 #endif
00248 };
00249 
00250 #endif //QT_NO_COMPONENT
00251 
00252 #endif //QLIBRARY_H

Generated at Wed Mar 3 13:21:58 2004 by doxygen1.2.8.1 written by Dimitri van Heesch, © 1997-2001