Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

DLL.h

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    DLL.h
00006  *
00007  *  $Id: DLL.h,v 1.1.1.4 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *  @author Kirthika Parameswaran <kirthika@cs.wustl.edu>
00010  */
00011 //=============================================================================
00012 
00013 
00014 #ifndef ACE_DLL_H
00015 #define ACE_DLL_H
00016 #include "ace/pre.h"
00017 
00018 #include "ace/OS.h"
00019 
00020 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00021 # pragma once
00022 #endif /* ACE_LACKS_PRAGMA_ONCE */
00023 
00024 class ACE_DLL_Handle;
00025 
00026 /**
00027  * @class ACE_DLL
00028  *
00029  * @brief Provides an abstract interface for handling various DLL
00030  * operations.
00031  *
00032  * This class is an wrapper over the various methods for utilizing
00033  * a dynamically linked library (DLL), which is called a shared
00034  * library on some platforms.  Operations open(), close(), and
00035  * symbol() have been implemented to help opening/closing and
00036  * extracting symbol information from a DLL, respectively.
00037  */
00038 class ACE_Export ACE_DLL
00039 {
00040 public:
00041   // = Initialization and termination methods.
00042 
00043   /// Default constructor.  By default, the close() operation on the
00044   /// object will be invoked before it is destroyed.
00045   ACE_DLL (int close_on_destruction = 1);
00046 
00047   /**
00048    * This constructor opens and dynamically links @a dll_name.  The
00049    * default mode is <RTLD_LAZY>, which loads identifier symbols but
00050    * not the symbols for functions, which are loaded dynamically
00051    * on-demand.  Other supported modes include: <RTLD_NOW>, which
00052    * performs all necessary relocations when @a dll_name is first
00053    * loaded and <RTLD_GLOBAL>, which makes symbols available for
00054    * relocation processing of any other DLLs.
00055    */
00056   ACE_DLL (const ACE_TCHAR *dll_name,
00057            int open_mode = ACE_DEFAULT_SHLIB_MODE,
00058            int close_on_destruction = 1);
00059 
00060   /// Copy constructor.
00061   ACE_DLL (const ACE_DLL &);
00062 
00063   /**
00064    * This method opens and dynamically links @a dll_name.  The default
00065    * mode is <RTLD_LAZY>, which loads identifier symbols but not the
00066    * symbols for functions, which are loaded dynamically on-demand.
00067    * Other supported modes include: <RTLD_NOW>, which performs all
00068    * necessary relocations when @a dll_name>is first loaded and
00069    * <RTLD_GLOBAL>, which makes symbols available for relocation
00070    * processing of any other DLLs.
00071    * @param dll_name The name of the dll.
00072    * @param open_mode How the dll is opened.
00073    * @param close_on_destruction Close the handle in the destructor.
00074    * @retval -1 On failure
00075    * @retval 0 On success.
00076    */
00077   int open (const ACE_TCHAR *dll_name,
00078             int open_mode = ACE_DEFAULT_SHLIB_MODE,
00079             int close_on_destruction = 1);
00080 
00081   /// Call to close the DLL object.
00082   int close (void);
00083 
00084   /**
00085    * Called when the DLL object is destroyed -- invokes close() if the
00086    * <close_on_destruction> flag is set in the constructor or open()
00087    * method.
00088    */
00089   ~ACE_DLL (void);
00090 
00091   /// If @a symbol_name is in the symbol table of the DLL a pointer to
00092   /// the @a symbol_name is returned.  Otherwise, returns 0.  Setting
00093   /// ignore_errors = 1 allows you to probe a dll without generating
00094   /// error messages in the log.  Handy for determining the capabilities
00095   /// of a library.
00096   void *symbol (const ACE_TCHAR *symbol_name, int ignore_errors = 0);
00097 
00098   /// Returns a pointer to a string explaining that an error occured.  You
00099   /// will need to consult the error log for the actual error string
00100   /// returned by the OS.
00101   ACE_TCHAR *error (void) const;
00102 
00103   /**
00104    * Return the handle to the caller.  If @a become_owner is non-0 then
00105    * caller assumes ownership of the handle and the ACE_DLL object
00106    * won't call close() when it goes out of scope, even if
00107    * <close_on_destruction> is set.
00108    */
00109   ACE_SHLIB_HANDLE get_handle (int become_owner = 0) const;
00110 
00111   /// Set the handle for the DLL object. By default, the close() operation on
00112   /// the object will be invoked before it is destroyed.
00113   int set_handle (ACE_SHLIB_HANDLE handle, int close_on_destruction = 1);
00114 
00115 private:
00116 
00117   int open_i (const ACE_TCHAR *dll_name,
00118               int open_mode = ACE_DEFAULT_SHLIB_MODE,
00119               int close_on_destruction = 1,
00120               ACE_SHLIB_HANDLE handle = 0);
00121 
00122 
00123   /// Open mode.
00124   int open_mode_;
00125 
00126   /// Keep track of the name of the loaded dll, so it can be used
00127   /// to remove framework components, singletons that live in the dll,
00128   /// prior to unloading the dll in the close() method.
00129   ACE_TCHAR *dll_name_;
00130 
00131   /// This flag keeps track of whether we should close the handle
00132   /// automatically when the destructor runs.
00133   int close_on_destruction_;
00134 
00135   ACE_DLL_Handle *dll_handle_;
00136 
00137   /// Flag to record if the last operation had an error.
00138   int error_;
00139 
00140   // = Disallow copying and assignment since we don't handle these.
00141   ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_DLL &))
00142 };
00143 
00144 #include "ace/post.h"
00145 #endif /* ACE_DLL_H */

Generated on Mon Jun 16 11:19:37 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002