| [190] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|---|
| 2 | <!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/tools/qlibrary.cpp:68 -->
|
|---|
| 3 | <html>
|
|---|
| 4 | <head>
|
|---|
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|---|
| 6 | <title>QLibrary Class</title>
|
|---|
| 7 | <style type="text/css"><!--
|
|---|
| 8 | fn { margin-left: 1cm; text-indent: -1cm; }
|
|---|
| 9 | a:link { color: #004faf; text-decoration: none }
|
|---|
| 10 | a:visited { color: #672967; text-decoration: none }
|
|---|
| 11 | body { background: #ffffff; color: black; }
|
|---|
| 12 | --></style>
|
|---|
| 13 | </head>
|
|---|
| 14 | <body>
|
|---|
| 15 |
|
|---|
| 16 | <table border="0" cellpadding="0" cellspacing="0" width="100%">
|
|---|
| 17 | <tr bgcolor="#E5E5E5">
|
|---|
| 18 | <td valign=center>
|
|---|
| 19 | <a href="index.html">
|
|---|
| 20 | <font color="#004faf">Home</font></a>
|
|---|
| 21 | | <a href="classes.html">
|
|---|
| 22 | <font color="#004faf">All Classes</font></a>
|
|---|
| 23 | | <a href="mainclasses.html">
|
|---|
| 24 | <font color="#004faf">Main Classes</font></a>
|
|---|
| 25 | | <a href="annotated.html">
|
|---|
| 26 | <font color="#004faf">Annotated</font></a>
|
|---|
| 27 | | <a href="groups.html">
|
|---|
| 28 | <font color="#004faf">Grouped Classes</font></a>
|
|---|
| 29 | | <a href="functions.html">
|
|---|
| 30 | <font color="#004faf">Functions</font></a>
|
|---|
| 31 | </td>
|
|---|
| 32 | <td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QLibrary Class Reference</h1>
|
|---|
| 33 |
|
|---|
| 34 | <p>The QLibrary class provides a wrapper for handling shared libraries.
|
|---|
| 35 | <a href="#details">More...</a>
|
|---|
| 36 | <p>All the functions in this class are <a href="threads.html#reentrant">reentrant</a> when Qt is built with thread support.</p>
|
|---|
| 37 | <p><tt>#include <<a href="qlibrary-h.html">qlibrary.h</a>></tt>
|
|---|
| 38 | <p><a href="qlibrary-members.html">List of all member functions.</a>
|
|---|
| 39 | <h2>Public Members</h2>
|
|---|
| 40 | <ul>
|
|---|
| 41 | <li class=fn><a href="#QLibrary"><b>QLibrary</b></a> ( const QString & filename )</li>
|
|---|
| 42 | <li class=fn>virtual <a href="#~QLibrary"><b>~QLibrary</b></a> ()</li>
|
|---|
| 43 | <li class=fn>void * <a href="#resolve"><b>resolve</b></a> ( const char * symb )</li>
|
|---|
| 44 | <li class=fn>bool <a href="#load"><b>load</b></a> ()</li>
|
|---|
| 45 | <li class=fn>virtual bool <a href="#unload"><b>unload</b></a> ()</li>
|
|---|
| 46 | <li class=fn>bool <a href="#isLoaded"><b>isLoaded</b></a> () const</li>
|
|---|
| 47 | <li class=fn>bool <a href="#autoUnload"><b>autoUnload</b></a> () const</li>
|
|---|
| 48 | <li class=fn>void <a href="#setAutoUnload"><b>setAutoUnload</b></a> ( bool enabled )</li>
|
|---|
| 49 | <li class=fn>QString <a href="#library"><b>library</b></a> () const</li>
|
|---|
| 50 | </ul>
|
|---|
| 51 | <h2>Static Public Members</h2>
|
|---|
| 52 | <ul>
|
|---|
| 53 | <li class=fn>void * <a href="#resolve-2"><b>resolve</b></a> ( const QString & filename, const char * symb )</li>
|
|---|
| 54 | </ul>
|
|---|
| 55 | <hr><a name="details"></a><h2>Detailed Description</h2>
|
|---|
| 56 |
|
|---|
| 57 |
|
|---|
| 58 |
|
|---|
| 59 | The QLibrary class provides a wrapper for handling shared libraries.
|
|---|
| 60 | <p>
|
|---|
| 61 |
|
|---|
| 62 | <p> An instance of a QLibrary object can handle a single shared
|
|---|
| 63 | library and provide access to the functionality in the library in
|
|---|
| 64 | a platform independent way. If the library is a component server,
|
|---|
| 65 | QLibrary provides access to the exported component and can
|
|---|
| 66 | directly query this component for interfaces.
|
|---|
| 67 | <p> QLibrary ensures that the shared library is loaded and stays in
|
|---|
| 68 | memory whilst it is in use. QLibrary can also unload the library
|
|---|
| 69 | on destruction and release unused resources.
|
|---|
| 70 | <p> A typical use of QLibrary is to resolve an exported symbol in a
|
|---|
| 71 | shared object, and to call the function that this symbol
|
|---|
| 72 | represents. This is called "explicit linking" in contrast to
|
|---|
| 73 | "implicit linking", which is done by the link step in the build
|
|---|
| 74 | process when linking an executable against a library.
|
|---|
| 75 | <p> The following code snippet loads a library, resolves the symbol
|
|---|
| 76 | "mysymbol", and calls the function if everything succeeded. If
|
|---|
| 77 | something went wrong, e.g. the library file does not exist or the
|
|---|
| 78 | symbol is not defined, the function pointer will be 0 and won't be
|
|---|
| 79 | called. When the QLibrary object is destroyed the library will be
|
|---|
| 80 | unloaded, making all references to memory allocated in the library
|
|---|
| 81 | invalid.
|
|---|
| 82 | <p> <pre>
|
|---|
| 83 | typedef void (*MyPrototype)();
|
|---|
| 84 | MyPrototype myFunction;
|
|---|
| 85 |
|
|---|
| 86 | QLibrary myLib( "mylib" );
|
|---|
| 87 | myFunction = (MyPrototype) myLib.<a href="#resolve">resolve</a>( "mysymbol" );
|
|---|
| 88 | if ( myFunction ) {
|
|---|
| 89 | myFunction();
|
|---|
| 90 | }
|
|---|
| 91 | </pre>
|
|---|
| 92 |
|
|---|
| 93 | <p>See also <a href="plugins.html">Plugins</a>.
|
|---|
| 94 |
|
|---|
| 95 | <hr><h2>Member Function Documentation</h2>
|
|---|
| 96 | <h3 class=fn><a name="QLibrary"></a>QLibrary::QLibrary ( const <a href="qstring.html">QString</a> & filename )
|
|---|
| 97 | </h3>
|
|---|
| 98 | Creates a QLibrary object for the shared library <em>filename</em>. The
|
|---|
| 99 | library will be unloaded in the destructor.
|
|---|
| 100 | <p> Note that <em>filename</em> does not need to include the (platform specific)
|
|---|
| 101 | file extension, so calling
|
|---|
| 102 | <pre>
|
|---|
| 103 | QLibrary lib( "mylib" );
|
|---|
| 104 | </pre>
|
|---|
| 105 |
|
|---|
| 106 | is equivalent to calling
|
|---|
| 107 | <pre>
|
|---|
| 108 | QLibrary lib( "mylib.dll" );
|
|---|
| 109 | </pre>
|
|---|
| 110 |
|
|---|
| 111 | on Windows, and
|
|---|
| 112 | <pre>
|
|---|
| 113 | QLibrary lib( "libmylib.so" );
|
|---|
| 114 | </pre>
|
|---|
| 115 |
|
|---|
| 116 | on Unix. Specifying the extension is not recommended, since
|
|---|
| 117 | doing so introduces a platform dependency.
|
|---|
| 118 | <p> If <em>filename</em> does not include a path, the library loader will
|
|---|
| 119 | look for the file in the platform specific search paths.
|
|---|
| 120 | <p> <p>See also <a href="#load">load</a>(), <a href="#unload">unload</a>(), and <a href="#setAutoUnload">setAutoUnload</a>().
|
|---|
| 121 |
|
|---|
| 122 | <h3 class=fn><a name="~QLibrary"></a>QLibrary::~QLibrary ()<tt> [virtual]</tt>
|
|---|
| 123 | </h3>
|
|---|
| 124 | Deletes the QLibrary object.
|
|---|
| 125 | <p> The library will be unloaded if <a href="#autoUnload">autoUnload</a>() is TRUE (the
|
|---|
| 126 | default), otherwise it stays in memory until the application
|
|---|
| 127 | exits.
|
|---|
| 128 | <p> <p>See also <a href="#unload">unload</a>() and <a href="#setAutoUnload">setAutoUnload</a>().
|
|---|
| 129 |
|
|---|
| 130 | <h3 class=fn>bool <a name="autoUnload"></a>QLibrary::autoUnload () const
|
|---|
| 131 | </h3>
|
|---|
| 132 | Returns TRUE if the library will be automatically unloaded when
|
|---|
| 133 | this wrapper object is destructed; otherwise returns FALSE. The
|
|---|
| 134 | default is TRUE.
|
|---|
| 135 | <p> <p>See also <a href="#setAutoUnload">setAutoUnload</a>().
|
|---|
| 136 |
|
|---|
| 137 | <h3 class=fn>bool <a name="isLoaded"></a>QLibrary::isLoaded () const
|
|---|
| 138 | </h3>
|
|---|
| 139 | Returns TRUE if the library is loaded; otherwise returns FALSE.
|
|---|
| 140 | <p> <p>See also <a href="#unload">unload</a>().
|
|---|
| 141 |
|
|---|
| 142 | <h3 class=fn><a href="qstring.html">QString</a> <a name="library"></a>QLibrary::library () const
|
|---|
| 143 | </h3>
|
|---|
| 144 | Returns the filename of the shared library this QLibrary object
|
|---|
| 145 | handles, including the platform specific file extension.
|
|---|
| 146 | <p> For example:
|
|---|
| 147 | <pre>
|
|---|
| 148 | QLibrary lib( "mylib" );
|
|---|
| 149 | <a href="qstring.html">QString</a> str = lib.<a href="#library">library</a>();
|
|---|
| 150 | </pre>
|
|---|
| 151 |
|
|---|
| 152 | will set <em>str</em> to "mylib.dll" on Windows, and "libmylib.so" on Linux.
|
|---|
| 153 |
|
|---|
| 154 | <h3 class=fn>bool <a name="load"></a>QLibrary::load ()
|
|---|
| 155 | </h3>
|
|---|
| 156 | Loads the library. Since <a href="#resolve">resolve</a>() always calls this function
|
|---|
| 157 | before resolving any symbols it is not necessary to call it
|
|---|
| 158 | explicitly. In some situations you might want the library loaded
|
|---|
| 159 | in advance, in which case you would use this function.
|
|---|
| 160 | <p> On Darwin and Mac OS X this function uses code from dlcompat, part of the
|
|---|
| 161 | OpenDarwin project.
|
|---|
| 162 | <p>
|
|---|
| 163 | <p> Copyright (c) 2002 Jorge Acereda and Peter O'Gorman
|
|---|
| 164 | <p> Permission is hereby granted, free of charge, to any person obtaining
|
|---|
| 165 | a copy of this software and associated documentation files (the
|
|---|
| 166 | "Software"), to deal in the Software without restriction, including
|
|---|
| 167 | without limitation the rights to use, copy, modify, merge, publish,
|
|---|
| 168 | distribute, sublicense, and/or sell copies of the Software, and to
|
|---|
| 169 | permit persons to whom the Software is furnished to do so, subject to
|
|---|
| 170 | the following conditions:
|
|---|
| 171 | <p> The above copyright notice and this permission notice shall be
|
|---|
| 172 | included in all copies or substantial portions of the Software.
|
|---|
| 173 | <p> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|---|
| 174 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|---|
| 175 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|---|
| 176 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
|---|
| 177 | LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
|---|
| 178 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
|---|
| 179 | WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|---|
| 180 |
|
|---|
| 181 | <h3 class=fn>void * <a name="resolve"></a>QLibrary::resolve ( const char * symb )
|
|---|
| 182 | </h3>
|
|---|
| 183 | Returns the address of the exported symbol <em>symb</em>. The library is
|
|---|
| 184 | loaded if necessary. The function returns 0 if the symbol could
|
|---|
| 185 | not be resolved or the library could not be loaded.
|
|---|
| 186 | <p> <pre>
|
|---|
| 187 | typedef int (*avgProc)( int, int );
|
|---|
| 188 |
|
|---|
| 189 | avgProc avg = (avgProc) library->resolve( "avg" );
|
|---|
| 190 | if ( avg )
|
|---|
| 191 | return avg( 5, 8 );
|
|---|
| 192 | else
|
|---|
| 193 | return -1;
|
|---|
| 194 | </pre>
|
|---|
| 195 |
|
|---|
| 196 | <p> The symbol must be exported as a C-function from the library. This
|
|---|
| 197 | requires the <tt>extern "C"</tt> notation if the library is compiled
|
|---|
| 198 | with a C++ compiler. On Windows you also have to explicitly export
|
|---|
| 199 | the function from the DLL using the <tt>__declspec(dllexport)</tt>
|
|---|
| 200 | compiler directive.
|
|---|
| 201 | <p> <pre>
|
|---|
| 202 | extern "C" MY_EXPORT_MACRO int avg(int a, int b)
|
|---|
| 203 | {
|
|---|
| 204 | return (a + b) / 2;
|
|---|
| 205 | }
|
|---|
| 206 | </pre>
|
|---|
| 207 |
|
|---|
| 208 | <p> with <tt>MY_EXPORT</tt> defined as
|
|---|
| 209 | <p> <pre>
|
|---|
| 210 | #ifdef Q_WS_WIN
|
|---|
| 211 | # define MY_EXPORT __declspec(dllexport)
|
|---|
| 212 | #else
|
|---|
| 213 | # define MY_EXPORT
|
|---|
| 214 | #endif
|
|---|
| 215 | </pre>
|
|---|
| 216 |
|
|---|
| 217 | <p> On Darwin and Mac OS X this function uses code from dlcompat, part of the
|
|---|
| 218 | OpenDarwin project.
|
|---|
| 219 | <p>
|
|---|
| 220 | <p> Copyright (c) 2002 Jorge Acereda and Peter O'Gorman
|
|---|
| 221 | <p> Permission is hereby granted, free of charge, to any person obtaining
|
|---|
| 222 | a copy of this software and associated documentation files (the
|
|---|
| 223 | "Software"), to deal in the Software without restriction, including
|
|---|
| 224 | without limitation the rights to use, copy, modify, merge, publish,
|
|---|
| 225 | distribute, sublicense, and/or sell copies of the Software, and to
|
|---|
| 226 | permit persons to whom the Software is furnished to do so, subject to
|
|---|
| 227 | the following conditions:
|
|---|
| 228 | <p> The above copyright notice and this permission notice shall be
|
|---|
| 229 | included in all copies or substantial portions of the Software.
|
|---|
| 230 | <p> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|---|
| 231 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|---|
| 232 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|---|
| 233 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
|---|
| 234 | LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
|---|
| 235 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
|---|
| 236 | WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|---|
| 237 |
|
|---|
| 238 | <h3 class=fn>void * <a name="resolve-2"></a>QLibrary::resolve ( const <a href="qstring.html">QString</a> & filename, const char * symb )<tt> [static]</tt>
|
|---|
| 239 | </h3>
|
|---|
| 240 | This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
|---|
| 241 | <p> Loads the library <em>filename</em> and returns the address of the
|
|---|
| 242 | exported symbol <em>symb</em>. Note that like the constructor, <em>filename</em> does not need to include the (platform specific) file
|
|---|
| 243 | extension. The library remains loaded until the process exits.
|
|---|
| 244 | <p> The function returns 0 if the symbol could not be resolved or the
|
|---|
| 245 | library could not be loaded.
|
|---|
| 246 | <p> This function is useful only if you want to resolve a single
|
|---|
| 247 | symbol, e.g. a function pointer from a specific library once:
|
|---|
| 248 | <p> <pre>
|
|---|
| 249 | typedef void (*FunctionType)();
|
|---|
| 250 | static FunctionType *ptrFunction = 0;
|
|---|
| 251 | static bool triedResolve = FALSE;
|
|---|
| 252 | if ( !ptrFunction && !triedResolve )
|
|---|
| 253 | ptrFunction = QLibrary::<a href="#resolve">resolve</a>( "mylib", "mysymb" );
|
|---|
| 254 |
|
|---|
| 255 | if ( ptrFunction )
|
|---|
| 256 | ptrFunction();
|
|---|
| 257 | else
|
|---|
| 258 | ...
|
|---|
| 259 | </pre>
|
|---|
| 260 |
|
|---|
| 261 | <p> If you want to resolve multiple symbols, use a QLibrary object and
|
|---|
| 262 | call the non-static version of <a href="#resolve">resolve</a>().
|
|---|
| 263 | <p> <p>See also
|
|---|
| 264 | <h3 class=fn>void <a name="setAutoUnload"></a>QLibrary::setAutoUnload ( bool enabled )
|
|---|
| 265 | </h3>
|
|---|
| 266 | If <em>enabled</em> is TRUE (the default), the wrapper object is set to
|
|---|
| 267 | automatically unload the library upon destruction. If <em>enabled</em>
|
|---|
| 268 | is FALSE, the wrapper object is not unloaded unless you explicitly
|
|---|
| 269 | call <a href="#unload">unload</a>().
|
|---|
| 270 | <p> <p>See also <a href="#autoUnload">autoUnload</a>().
|
|---|
| 271 |
|
|---|
| 272 | <h3 class=fn>bool <a name="unload"></a>QLibrary::unload ()<tt> [virtual]</tt>
|
|---|
| 273 | </h3>
|
|---|
| 274 | Unloads the library and returns TRUE if the library could be
|
|---|
| 275 | unloaded; otherwise returns FALSE.
|
|---|
| 276 | <p> This function is called by the destructor if <a href="#autoUnload">autoUnload</a>() is
|
|---|
| 277 | enabled.
|
|---|
| 278 | <p> <p>See also <a href="#resolve">resolve</a>().
|
|---|
| 279 |
|
|---|
| 280 | <!-- eof -->
|
|---|
| 281 | <hr><p>
|
|---|
| 282 | This file is part of the <a href="index.html">Qt toolkit</a>.
|
|---|
| 283 | Copyright © 1995-2007
|
|---|
| 284 | <a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
|
|---|
| 285 | <table width=100% cellspacing=0 border=0><tr>
|
|---|
| 286 | <td>Copyright © 2007
|
|---|
| 287 | <a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
|
|---|
| 288 | <td align=right><div align=right>Qt 3.3.8</div>
|
|---|
| 289 | </table></div></address></body>
|
|---|
| 290 | </html>
|
|---|
