You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
291 lines
12 KiB
291 lines
12 KiB
14 years ago
|
<!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>QLibrary 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>QLibrary Class Reference</h1>
|
||
|
|
|
||
|
|
<p>The QLibrary 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 Qt 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="#QLibrary"><b>QLibrary</b></a> ( const QString & filename )</li>
|
||
|
|
<li class=fn>virtual <a href="#~QLibrary"><b>~QLibrary</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>QString <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 QString & filename, const char * symb )</li>
|
||
|
|
</ul>
|
||
|
|
<hr><a name="details"></a><h2>Detailed Description</h2>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
The QLibrary class provides a wrapper for handling shared libraries.
|
||
|
|
<p>
|
||
|
|
|
||
|
|
<p> 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.
|
||
|
|
<p> 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.
|
||
|
|
<p> 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.
|
||
|
|
<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 QLibrary 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;
|
||
|
|
|
||
|
|
QLibrary 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="QLibrary"></a>QLibrary::QLibrary ( const <a href="qstring.html">QString</a> & filename )
|
||
|
|
</h3>
|
||
|
|
Creates a QLibrary 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>
|
||
|
|
QLibrary lib( "mylib" );
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
is equivalent to calling
|
||
|
|
<pre>
|
||
|
|
QLibrary lib( "mylib.dll" );
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
on Windows, and
|
||
|
|
<pre>
|
||
|
|
QLibrary 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="~QLibrary"></a>QLibrary::~QLibrary ()<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Deletes the QLibrary 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>QLibrary::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>QLibrary::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">QString</a> <a name="library"></a>QLibrary::library () const
|
||
|
|
</h3>
|
||
|
|
Returns the filename of the shared library this QLibrary object
|
||
|
|
handles, including the platform specific file extension.
|
||
|
|
<p> For example:
|
||
|
|
<pre>
|
||
|
|
QLibrary lib( "mylib" );
|
||
|
|
<a href="qstring.html">QString</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>QLibrary::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>QLibrary::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
|
||
|
|
requires 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>QLibrary::resolve ( const <a href="qstring.html">QString</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 = QLibrary::<a href="#resolve">resolve</a>( "mylib", "mysymb" );
|
||
|
|
|
||
|
|
if ( ptrFunction )
|
||
|
|
ptrFunction();
|
||
|
|
else
|
||
|
|
...
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> If you want to resolve multiple symbols, use a QLibrary 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>QLibrary::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>QLibrary::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">Qt 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>Qt 3.3.8</div>
|
||
|
|
</table></div></address></body>
|
||
|
|
</html>
|