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