Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions

QLibrary Class Reference

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

#include <qlibrary.h>

List of all member functions.

Public Members

Static 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 executable against a library.

The following code snipplet will load a library, resolve the symbol "mysymbol", and call 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 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. Since the lifetime of the interface is reference controlled it is also impossible to unload the library when there are references to memory allocated in the library.

If provided by the component, QLibrary uses the QLibraryInterface implementation to control the initializing and unloading of the library. For more information, see the implementation of this interface in the style plugins that ship with Qt.

See also Component Model.


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. If filename does not include a path, the library loader will look for the file in the platform specific search paths.

See also setPolicy() and unload().

QLibrary::~QLibrary ()

Deletes the QLibrary object. The library will be unloaded if the policy is not Manual, otherwise it stays in memory until the application is exited.

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. request and iface are propagated to the component's queryInterface implementation.

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 a null pointer if the symbol could not be resolved or the library could not be loaded.

  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::resolve ( const QString & filename, const char * symb ) [static]

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Loads the library filename and returns the address of the exported symbol symb. Note that like for the constructor, filename does not need to include the (platform specific) file extension. The library keeps loaded until the process exits.

The function returns a null pointer if the symbol could not be resolved or the library could not be loaded.

void QLibrary::setPolicy ( Policy pol )

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

bool QLibrary::unload ()

Unloads the library and returns TRUE if the library could be unloaded, otherwise returns FALSE.

Any component referenced by the QLibrary object is being released before the library is unloaded. If the component implements the QLibraryInterface, the cleanup() function is called. if the subsequent call to canUnload() return FALSE, unloading will be cancelled.

This function is called by the destructor if the policy is not Manual.

See also queryInterface() and resolve().


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


Copyright © 2001 TrolltechTrademarks
Qt version 3.0.0-beta5