DLL.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    DLL.h
00006  *
00007  *  DLL.h,v 4.39 2006/05/30 18:33:59 schmidt Exp
00008  *
00009  *  @author Kirthika Parameswaran <kirthika@cs.wustl.edu>
00010  */
00011 //=============================================================================
00012 
00013 #ifndef ACE_DLL_H
00014 #define ACE_DLL_H
00015 #include /**/ "ace/pre.h"
00016 
00017 #include "ace/ACE_export.h"
00018 
00019 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00020 # pragma once
00021 #endif /* ACE_LACKS_PRAGMA_ONCE */
00022 
00023 #include "ace/Global_Macros.h"
00024 #include "ace/os_include/os_dlfcn.h"
00025 
00026 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
00027 
00028 class ACE_DLL_Handle;
00029 
00030 /**
00031  * @class ACE_DLL
00032  *
00033  * @brief Provides an abstract interface for handling various DLL
00034  * operations.
00035  *
00036  * This class is a wrapper over the various methods for utilizing
00037  * a dynamically linked library (DLL), which is called a shared
00038  * library on some platforms.  Operations @c open(), @c close(), and
00039  * @c symbol() have been implemented to help opening/closing and
00040  * extracting symbol information from a DLL, respectively.
00041  */
00042 class ACE_Export ACE_DLL
00043 {
00044 public:
00045   // = Initialization and termination methods.
00046 
00047   /**
00048    * Default constructor.  By default, the close() operation on the
00049    * object will be invoked before it is destroyed.
00050    * @param close_handle_on_destruction  Indicates whether or not the
00051    *        close() method will be called to close an open DLL when this
00052    *        object is destroyed. By default, close() will be called.
00053    *        Set this parameter to 0 for situations where the DLL's lifetime
00054    *        is controlled in a scope other than that of this ACE_DLL object.
00055    *        For example, termination by ACE_DLL_Manager via ACE::fini().
00056    */
00057   explicit ACE_DLL (int close_handle_on_destruction = 1);
00058 
00059   /// Allow assignment
00060   const ACE_DLL& operator= (const ACE_DLL &rhs);
00061 
00062 
00063   /**
00064    * This constructor performs the actions of open() during construction.
00065    * @param dll_name  The name or path of the DLL to load.
00066    * @param open_mode  Flags to alter the actions taken when loading the DLL.
00067    *        The possible values are:
00068    *        @li @c RTLD_LAZY (this the default): loads identifier symbols but
00069    *            not the symbols for functions, which are loaded dynamically
00070    *            on-demand.
00071    *        @li @c RTLD_NOW: performs all necessary relocations when
00072    *            @a dll_name is first loaded
00073    *        @li RTLD_GLOBAL: makes symbols available for relocation
00074    *            processing of any other DLLs.
00075    * @param close_handle_on_destruction  Indicates whether or not the
00076    *        close() method will be called to close an open DLL when this
00077    *        object is destroyed. By default, close() will be called.
00078    *        Set this parameter to 0 for situations where the DLL's lifetime
00079    *        is controlled in a scope other than that of this ACE_DLL object.
00080    *        For example, termination by ACE_DLL_Manager via ACE::fini().
00081    */
00082   explicit ACE_DLL (const ACE_TCHAR *dll_name,
00083                     int open_mode = ACE_DEFAULT_SHLIB_MODE,
00084                     int close_handle_on_destruction = 1);
00085 
00086   /// Copy constructor.
00087   ACE_DLL (const ACE_DLL &);
00088 
00089   /**
00090    * This method opens and dynamically links a specified DLL.
00091    * @param dll_name  The filename or path of the DLL to load.
00092    *        If a filename is given to @c open(), the @c ACE::ldfind() is used
00093    *        to locate DLLs via the following algorithms: (1) DLL filename
00094    *        expansion: @c ACE::ldfind() determines the name of the DLL by
00095    *        adding the appropriate prefix and suffix, e.g., it adds the @c lib
00096    *        prefix and @c .so suffix for Solaris and the @c .dll suffix for
00097    *        Windows and (2) DLL search path: @c ACE::ldfind() will also search
00098    *        for the designated DLL using the platform's DLL search path
00099    *        environment variable, e.g., it searches for DLLs using @c
00100    *        LD_LIBRARY_PATH on many UNIX systems and @c PATH on Windows.
00101    * @param open_mode  Flags to alter the actions taken when loading the DLL.
00102    *        The possible values are:
00103    *        @li @c RTLD_LAZY (this the default): loads identifier symbols but
00104    *            not the symbols for functions, which are loaded dynamically
00105    *            on-demand.
00106    *        @li @c RTLD_NOW: performs all necessary relocations when
00107    *            @a dll_name is first loaded
00108    *        @li RTLD_GLOBAL: makes symbols available for relocation
00109    *            processing of any other DLLs.
00110    * @param close_handle_on_destruction  Indicates whether or not the
00111    *        close() method will be called to close an open DLL when this
00112    *        object is destroyed. By default, close() will be called.
00113    *        Set this parameter to 0 for situations where the DLL's lifetime
00114    *        is controlled in a scope other than that of this ACE_DLL object.
00115    *        For example, termination by ACE_DLL_Manager via ACE::fini().
00116    * @retval -1 On failure
00117    * @retval 0 On success.
00118    */
00119   int open (const ACE_TCHAR *dll_name,
00120             int open_mode = ACE_DEFAULT_SHLIB_MODE,
00121             int close_handle_on_destruction = 1);
00122 
00123   /// Call to close the DLL object.
00124   int close (void);
00125 
00126   /**
00127    * Called when the DLL object is destroyed -- invokes close() if the
00128    * @a close_handle_on_destruction flag was set to non-zero in the
00129    * constructor or open() method.
00130    */
00131   ~ACE_DLL (void);
00132 
00133   /**
00134    * Look up a named symbol in the DLL. DLL must be successfully opened
00135    * before calling symbol().
00136    * @param symbol_name The symbol name to look up.
00137    * @param ignore_errors If set to 1, allows you to probe a dll without
00138    *        generating error messages in the log.  Handy for determining
00139    *        the capabilities of a library.
00140    * @return Returns the value of @a symbol_name if it is a valid symbol
00141    *        in the DLL. Otherwise, returns 0.
00142    */
00143   void *symbol (const ACE_TCHAR *symbol_name, int ignore_errors = 0);
00144 
00145   /// Returns a pointer to a string explaining that an error occured.  You
00146   /// will need to consult the error log for the actual error string
00147   /// returned by the OS.
00148   ACE_TCHAR *error (void) const;
00149 
00150   /**
00151    * Return the handle to the caller.  If @a become_owner is non-0 then
00152    * caller assumes ownership of the handle and the ACE_DLL object
00153    * won't call close() when it goes out of scope, even if
00154    * <close_handle_on_destruction> is set.
00155    */
00156   ACE_SHLIB_HANDLE get_handle (int become_owner = 0) const;
00157 
00158   /// Set the handle for the DLL object. By default, the close()
00159   //operation on / the object will be invoked before it is destroyed.
00160   int set_handle (ACE_SHLIB_HANDLE handle,
00161                   int close_handle_on_destruction = 1);
00162 
00163 private:
00164 
00165   int open_i (const ACE_TCHAR *dll_name,
00166               int open_mode = ACE_DEFAULT_SHLIB_MODE,
00167               int close_handle_on_destruction = 1,
00168               ACE_SHLIB_HANDLE handle = 0);
00169 
00170 
00171   //private:
00172 public:
00173 
00174   /// Open mode.
00175   int open_mode_;
00176 
00177   /// Keep track of the name of the loaded dll, so it can be used
00178   /// to remove framework components, singletons that live in the dll,
00179   /// prior to unloading the dll in the close() method.
00180   ACE_TCHAR *dll_name_;
00181 
00182   /// This flag keeps track of whether we should close the handle
00183   /// automatically when the object is destroyed.
00184   int close_handle_on_destruction_;
00185 
00186   ACE_DLL_Handle *dll_handle_;
00187 
00188   /// Flag to record if the last operation had an error.
00189   int error_;
00190 
00191 };
00192 
00193 ACE_END_VERSIONED_NAMESPACE_DECL
00194 
00195 #include /**/ "ace/post.h"
00196 #endif /* ACE_DLL_H */

Generated on Thu Nov 9 09:41:50 2006 for ACE by doxygen 1.3.6