#ifndef CPPUNIT_PLUGIN_DYNAMICLIBRARYMANAGER_H

#define CPPUNIT_PLUGIN_DYNAMICLIBRARYMANAGER_H

#include <cppunit/Portability.h>

#include <string>

#if !defined(CPPUNIT_NO_TESTPLUGIN)

CPPUNIT_NS_BEGIN

/*! \brief Manages dynamic libraries.

 *

 * The Dynamic Library Manager provides a platform independent way to work with

 * dynamic library. It load a specific dynamic library, and can returns specific

 * symbol exported by the dynamic library.

 *

 * If an error occurs, a DynamicLibraryManagerException is thrown.

 *

 * \internal Implementation of the OS independent methods is in 

 * DynamicLibraryManager.cpp.

 *

 * \internal Porting to a new platform:

 * - Adds platform detection in config/SelectDllLoader.h. Should define a specific

 *   macro for that platform of the form: CPPUNIT_HAVE_XYZ_DLL_LOADER, where

 *   XYZ is the platform.

 * - Makes a copy of UnixDynamicLibraryManager.cpp and named it after the platform.

 * - Updated the 'guard' in your file (CPPUNIT_HAVE_XYZ_DLL_LOADER) so that it is

 *   only processed if the matching platform has been detected.

 * - Change the implementation of methods doLoadLibrary(), doReleaseLibrary(), 

 *   doFindSymbol() in your copy. Those methods usually maps directly to OS calls.

 * - Adds the file to the project.

 */

class DynamicLibraryManager

{

public:

  typedef void *Symbol;

  typedef void *LibraryHandle;

  /*! \brief Loads the specified library.

   * \param libraryFileName Name of the library to load.

   * \exception DynamicLibraryManagerException if a failure occurs while loading

   *            the library (fail to found or load the library).

   */

  DynamicLibraryManager( const std::string &libraryFileName );

  /// Releases the loaded library..

  ~DynamicLibraryManager();

  /*! \brief Returns a pointer on the specified symbol exported by the library.

   * \param symbol Name of the symbol exported by the library.

   * \return Pointer on the symbol. Should be casted to the actual type. Never \c NULL.

   * \exception DynamicLibraryManagerException if the symbol is not found.

   */

  Symbol findSymbol( const std::string &symbol );

private:

  /*! Loads the specified library.

   * \param libraryName Name of the library to load.

   * \exception DynamicLibraryManagerException if a failure occurs while loading

   *            the library (fail to found or load the library).

   */

  void loadLibrary( const std::string &libraryName );

  /*! Releases the loaded library.

   * 

   * \warning Must NOT throw any exceptions (called from destructor).

   */

  void releaseLibrary();

  /*! Loads the specified library.

   * 

   * May throw any exceptions (indicates failure).

   * \param libraryName Name of the library to load.

   * \return Handle of the loaded library. \c NULL indicates failure.

   */

  LibraryHandle doLoadLibrary( const std::string &libraryName );

  /*! Releases the loaded library.

   *

   * The handle of the library to free is in \c m_libraryHandle. It is never

   * \c NULL.

   * \warning Must NOT throw any exceptions (called from destructor).

   */

  void doReleaseLibrary();

  /*! Returns a pointer on the specified symbol exported by the library.

   * 

   * May throw any exceptions (indicates failure).

   * \param symbol Name of the symbol exported by the library.

   * \return Pointer on the symbol. \c NULL indicates failure.

   */

  Symbol doFindSymbol( const std::string &symbol );

  /*! Returns detailed information about doLoadLibrary() failure.

   *

   * Called just after a failed call to doLoadLibrary() to get extra

   * error information.

   *

   * \return Detailed information about the failure of the call to

   *         doLoadLibrary() that just failed.

   */

  std::string getLastErrorDetail() const;

  /// Prevents the use of the copy constructor.

  DynamicLibraryManager( const DynamicLibraryManager &copy );

  /// Prevents the use of the copy operator.

  void operator =( const DynamicLibraryManager &copy );

private:

  LibraryHandle m_libraryHandle;

  std::string m_libraryName;

};

CPPUNIT_NS_END

#endif // !defined(CPPUNIT_NO_TESTPLUGIN)

#endif  // CPPUNIT_PLUGIN_DYNAMICLIBRARYMANAGER_H