diff options
Diffstat (limited to 'doc/html/qlibrary.html')
| -rw-r--r-- | doc/html/qlibrary.html | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/doc/html/qlibrary.html b/doc/html/qlibrary.html new file mode 100644 index 000000000..be75bd858 --- /dev/null +++ b/doc/html/qlibrary.html @@ -0,0 +1,290 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/tools/qlibrary.cpp:68 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>TQLibrary Class</title> +<style type="text/css"><!-- +fn { margin-left: 1cm; text-indent: -1cm; } +a:link { color: #004faf; text-decoration: none } +a:visited { color: #672967; text-decoration: none } +body { background: #ffffff; color: black; } +--></style> +</head> +<body> + +<table border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr bgcolor="#E5E5E5"> +<td valign=center> + <a href="index.html"> +<font color="#004faf">Home</font></a> + | <a href="classes.html"> +<font color="#004faf">All Classes</font></a> + | <a href="mainclasses.html"> +<font color="#004faf">Main Classes</font></a> + | <a href="annotated.html"> +<font color="#004faf">Annotated</font></a> + | <a href="groups.html"> +<font color="#004faf">Grouped Classes</font></a> + | <a href="functions.html"> +<font color="#004faf">Functions</font></a> +</td> +<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>TQLibrary Class Reference</h1> + +<p>The TQLibrary class provides a wrapper for handling shared libraries. +<a href="#details">More...</a> +<p>All the functions in this class are <a href="threads.html#reentrant">reentrant</a> when TQt is built with thread support.</p> +<p><tt>#include <<a href="qlibrary-h.html">qlibrary.h</a>></tt> +<p><a href="qlibrary-members.html">List of all member functions.</a> +<h2>Public Members</h2> +<ul> +<li class=fn><a href="#TQLibrary"><b>TQLibrary</b></a> ( const TQString & filename )</li> +<li class=fn>virtual <a href="#~TQLibrary"><b>~TQLibrary</b></a> ()</li> +<li class=fn>void * <a href="#resolve"><b>resolve</b></a> ( const char * symb )</li> +<li class=fn>bool <a href="#load"><b>load</b></a> ()</li> +<li class=fn>virtual bool <a href="#unload"><b>unload</b></a> ()</li> +<li class=fn>bool <a href="#isLoaded"><b>isLoaded</b></a> () const</li> +<li class=fn>bool <a href="#autoUnload"><b>autoUnload</b></a> () const</li> +<li class=fn>void <a href="#setAutoUnload"><b>setAutoUnload</b></a> ( bool enabled )</li> +<li class=fn>TQString <a href="#library"><b>library</b></a> () const</li> +</ul> +<h2>Static Public Members</h2> +<ul> +<li class=fn>void * <a href="#resolve-2"><b>resolve</b></a> ( const TQString & filename, const char * symb )</li> +</ul> +<hr><a name="details"></a><h2>Detailed Description</h2> + + + +The TQLibrary class provides a wrapper for handling shared libraries. +<p> + +<p> An instance of a TQLibrary 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, +TQLibrary provides access to the exported component and can +directly query this component for interfaces. +<p> TQLibrary ensures that the shared library is loaded and stays in +memory whilst it is in use. TQLibrary can also unload the library +on destruction and release unused resources. +<p> A typical use of TQLibrary 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. +<p> 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 TQLibrary object is destroyed the library will be +unloaded, making all references to memory allocated in the library +invalid. +<p> <pre> + typedef void (*MyPrototype)(); + MyPrototype myFunction; + + TQLibrary myLib( "mylib" ); + myFunction = (MyPrototype) myLib.<a href="#resolve">resolve</a>( "mysymbol" ); + if ( myFunction ) { + myFunction(); + } + </pre> + +<p>See also <a href="plugins.html">Plugins</a>. + +<hr><h2>Member Function Documentation</h2> +<h3 class=fn><a name="TQLibrary"></a>TQLibrary::TQLibrary ( const <a href="qstring.html">TQString</a> & filename ) +</h3> +Creates a TQLibrary object for the shared library <em>filename</em>. The +library will be unloaded in the destructor. +<p> Note that <em>filename</em> does not need to include the (platform specific) +file extension, so calling +<pre> + TQLibrary lib( "mylib" ); + </pre> + +is equivalent to calling +<pre> + TQLibrary lib( "mylib.dll" ); + </pre> + +on Windows, and +<pre> + TQLibrary lib( "libmylib.so" ); + </pre> + +on Unix. Specifying the extension is not recommended, since +doing so introduces a platform dependency. +<p> If <em>filename</em> does not include a path, the library loader will +look for the file in the platform specific search paths. +<p> <p>See also <a href="#load">load</a>(), <a href="#unload">unload</a>(), and <a href="#setAutoUnload">setAutoUnload</a>(). + +<h3 class=fn><a name="~TQLibrary"></a>TQLibrary::~TQLibrary ()<tt> [virtual]</tt> +</h3> +Deletes the TQLibrary object. +<p> The library will be unloaded if <a href="#autoUnload">autoUnload</a>() is TRUE (the +default), otherwise it stays in memory until the application +exits. +<p> <p>See also <a href="#unload">unload</a>() and <a href="#setAutoUnload">setAutoUnload</a>(). + +<h3 class=fn>bool <a name="autoUnload"></a>TQLibrary::autoUnload () const +</h3> +Returns TRUE if the library will be automatically unloaded when +this wrapper object is destructed; otherwise returns FALSE. The +default is TRUE. +<p> <p>See also <a href="#setAutoUnload">setAutoUnload</a>(). + +<h3 class=fn>bool <a name="isLoaded"></a>TQLibrary::isLoaded () const +</h3> +Returns TRUE if the library is loaded; otherwise returns FALSE. +<p> <p>See also <a href="#unload">unload</a>(). + +<h3 class=fn><a href="qstring.html">TQString</a> <a name="library"></a>TQLibrary::library () const +</h3> +Returns the filename of the shared library this TQLibrary object +handles, including the platform specific file extension. +<p> For example: +<pre> + TQLibrary lib( "mylib" ); + <a href="qstring.html">TQString</a> str = lib.<a href="#library">library</a>(); + </pre> + +will set <em>str</em> to "mylib.dll" on Windows, and "libmylib.so" on Linux. + +<h3 class=fn>bool <a name="load"></a>TQLibrary::load () +</h3> +Loads the library. Since <a href="#resolve">resolve</a>() 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. +<p> On Darwin and Mac OS X this function uses code from dlcompat, part of the +OpenDarwin project. +<p> +<p> Copyright (c) 2002 Jorge Acereda and Peter O'Gorman +<p> 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: +<p> The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. +<p> 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. + +<h3 class=fn>void * <a name="resolve"></a>TQLibrary::resolve ( const char * symb ) +</h3> +Returns the address of the exported symbol <em>symb</em>. The library is +loaded if necessary. The function returns 0 if the symbol could +not be resolved or the library could not be loaded. +<p> <pre> + typedef int (*avgProc)( int, int ); + + avgProc avg = (avgProc) library->resolve( "avg" ); + if ( avg ) + return avg( 5, 8 ); + else + return -1; + </pre> + +<p> The symbol must be exported as a C-function from the library. This +retquires the <tt>extern "C"</tt> 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 <tt>__declspec(dllexport)</tt> +compiler directive. +<p> <pre> + extern "C" MY_EXPORT_MACRO int avg(int a, int b) + { + return (a + b) / 2; + } + </pre> + +<p> with <tt>MY_EXPORT</tt> defined as +<p> <pre> + #ifdef Q_WS_WIN + # define MY_EXPORT __declspec(dllexport) + #else + # define MY_EXPORT + #endif + </pre> + +<p> On Darwin and Mac OS X this function uses code from dlcompat, part of the +OpenDarwin project. +<p> +<p> Copyright (c) 2002 Jorge Acereda and Peter O'Gorman +<p> 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: +<p> The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. +<p> 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. + +<h3 class=fn>void * <a name="resolve-2"></a>TQLibrary::resolve ( const <a href="qstring.html">TQString</a> & filename, const char * symb )<tt> [static]</tt> +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Loads the library <em>filename</em> and returns the address of the +exported symbol <em>symb</em>. Note that like the constructor, <em>filename</em> does not need to include the (platform specific) file +extension. The library remains loaded until the process exits. +<p> The function returns 0 if the symbol could not be resolved or the +library could not be loaded. +<p> This function is useful only if you want to resolve a single +symbol, e.g. a function pointer from a specific library once: +<p> <pre> + typedef void (*FunctionType)(); + static FunctionType *ptrFunction = 0; + static bool triedResolve = FALSE; + if ( !ptrFunction && !triedResolve ) + ptrFunction = TQLibrary::<a href="#resolve">resolve</a>( "mylib", "mysymb" ); + + if ( ptrFunction ) + ptrFunction(); + else + ... + </pre> + +<p> If you want to resolve multiple symbols, use a TQLibrary object and +call the non-static version of <a href="#resolve">resolve</a>(). +<p> <p>See also +<h3 class=fn>void <a name="setAutoUnload"></a>TQLibrary::setAutoUnload ( bool enabled ) +</h3> +If <em>enabled</em> is TRUE (the default), the wrapper object is set to +automatically unload the library upon destruction. If <em>enabled</em> +is FALSE, the wrapper object is not unloaded unless you explicitly +call <a href="#unload">unload</a>(). +<p> <p>See also <a href="#autoUnload">autoUnload</a>(). + +<h3 class=fn>bool <a name="unload"></a>TQLibrary::unload ()<tt> [virtual]</tt> +</h3> +Unloads the library and returns TRUE if the library could be +unloaded; otherwise returns FALSE. +<p> This function is called by the destructor if <a href="#autoUnload">autoUnload</a>() is +enabled. +<p> <p>See also <a href="#resolve">resolve</a>(). + +<!-- eof --> +<hr><p> +This file is part of the <a href="index.html">TQt toolkit</a>. +Copyright © 1995-2007 +<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center> +<table width=100% cellspacing=0 border=0><tr> +<td>Copyright © 2007 +<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a> +<td align=right><div align=right>TQt 3.3.8</div> +</table></div></address></body> +</html> |