Classes - Annotated - Tree - Functions - Home - Structure

QLibrary Class Reference

The API for this class is under development and is subject to change.
We do not recommend the use of this class for production work at this time.

The QLibrary class provides a wrapper for handling shared libraries. More...

#include <qlibrary.h>

List of all member functions.

Public Members


Detailed Description

The QLibrary class provides a wrapper for handling shared libraries.

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.

QLibrary makes sure that the shared library is loaded and stays in memory for the time it is being used, and can also unload the library upon destruction and thus release unused resources.

A typical use of QLibrary is to resolve an exported symbol in a shared object, and to e.g. 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 binary against a library.

The following code snipplet will load a library, resolve the symbol "mysymbol", and call the function if everything succeeded. If anything went wrong, e.g. the library file is not existing, or the symbol is not defined, the function pointer will become a null pointer. Upon destruction of the QLibrary object the library will be unloaded again, making all referenced to memory allocated in the library invalid.

  typedef void (*MyPrototype)();
  MyPrototype myFunction;

  QLibrary myLib( "mylib" );
  myFunction = (MyProtoype)myLib.resolve( "mysymbol" );
  if ( myFunction ) {
    myFunction();
  }
  

Using this mechanism is only safe when the correct type of the function in the shared object is guaranteed - a wrong type might crash the application or leave it in an unstable state. Keeping a reference to the function pointer is also dangerous, as the library might be unloaded.

A safe and thus commonly used architecture for explicit linking of symbols is to use interfaces and components. QLibrary supports the component model in Qt with the queryInterface function.

  MySpecialInterface *iface = 0;

  QLibrary myLib( "mylib" );
  if ( myLib.queryInterface( IID_MySpecial, (QUnknownInterface**)&iface ) == QS_OK ) {
      iface->myFunction();
      iface->release();
  }
  

The shared object "mylib", which now acts as a component server, is guaranteed to provide a pointer to the correct interface type, so that it becomes safe to use unknown libraries in an application.


Member Type Documentation

QLibrary::Policy

This enum type defines the various policies a QLibrary can have with respect to loading and unloading the shared library.

The policy can be:


Member Function Documentation

QLibrary::QLibrary ( const QString & filename, Policy pol = Delayed )

Creates a QLibrary object for the shared library filename. The library get's loaded if pol is Immediately.

Note that filename does not need to include the (platform specific) file extension, so calling

  QLibrary lib( "mylib" );
  

would be equivalent to

  QLibrary lib( "mylib.dll" );
  

on Windows. But "mylib.dll" will obviously not work on other platforms.

See also setPolicy() and unload().

QLibrary::~QLibrary ()

Deletes the QLibrary object. The library will be unloaded if the policy is not Manual.

See also unload() and setPolicy().

bool QLibrary::isLoaded () const

Returns whether the library is loaded.

See also unload.

QString QLibrary::library () const

Returns the filename of the shared library this QLibrary object handles, including the platform specific file extension.

  QLibrary lib( "mylib" );
  QString str = lib.library();
  

will set str to "mylib.dll" on Windows, and "libmylib.so" on Linux.

Policy QLibrary::policy () const

Returns the current policy.

See also setPolicy.

QRESULT QLibrary::queryInterface ( const QUuid & request, QUnknownInterface ** iface )

Forwards the query to the component and returns the result. The library gets loaded if necessary.

See also QUnknownInterface::queryInterface.

void * QLibrary::resolve ( const char * symb )

Returns the address of the exported symbol symb. The library gets loaded if necessary. The function returns NULL if the symbol could not be resolved, or if loading the library failed.

  typedef int (*addProc)( int, int );

  addProc add = (addProc) library->resolve( "add" );
  if ( add )
      return add( 5, 8 );
  else
      return 5 + 8;
  

See also queryInterface.

void QLibrary::setPolicy ( Policy pol )

Sets the current policy to pol. The library is loaded if pol is set to Immediately.

See also LibraryPolicy.

bool QLibrary::unload ( bool force = FALSE )

Releases the component and unloads the library when successful. Returns TRUE if the library could be unloaded, otherwise FALSE. If the component implements the QLibraryInterface, the cleanup() function of this interface will be called. The unloading will be cancelled if the subsequent call to canUnload() returns FALSE.

This function gets called automatically in the destructor if the policy is not Manual.

Warning: If force is set to TRUE, the library gets unloaded at any cost, which is in most cases a segmentation fault, so you should know what you're doing!

See also queryInterface and resolve.


Search the documentation, FAQ, qt-interest archive and more (uses www.trolltech.com):


This file is part of the Qt toolkit, copyright © 1995-2001 Trolltech, all rights reserved.


Copyright © 2001 TrolltechTrademarks
Qt version 3.0.0-beta2